https://oxpedia.org/wiki/api.php?action=feedcontributions&user=Dennis+Sieben&feedformat=atomOpen-Xchange - User contributions [en]2024-03-29T10:08:31ZUser contributionsMediaWiki 1.31.0https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver&diff=25284AppSuite:GuardMailResolver2020-04-06T15:47:37Z<p>Dennis Sieben: </p>
<hr />
<div>= Mail Resolver =<br />
<br />
When a Guard user sends an email to a recipient, Guard must be able to determine if the recipient is an OX user, or if that person uses a different email service. If the recipient is an OX user, Guard must be able to determine the users ID and context. This is done through the OX backend by default, which in turn looks up the email address using the default login2context table. Guard can, however, be configured to use a different URL for third party or custom handlers.<br />
<br />
<br />
== Default Handler ==<br />
<br />
By default, Guard will try to resolve the email address against the OX middleware. The OX middleware must be able to resolve the email address using the login lookup tables. Email domains must not span multiple contexts. In addition, if a context is defined as a default login, the context must also be defined with the domains that exist within.<br />
<br />
For example, if you created a default context (say context 1) using<br />
<br />
/opt/open-xchange/sbin/createcontext -A oxadminmaster -P admin_master_password -c 1 \<br />
-u oxadmin -d "Context Admin" -g Admin -s User -p admin_password **-L defaultcontext** ...<br />
<br />
You must add the domain (substitue for company.com) for that context using<br />
<br />
./changecontext -A oxadminmaster -P secret -c 1 -L company.com<br />
You can add multiple domains to the context at the same time, seperating by ”,”<br />
<br />
<br />
=== Variant of the default handler supported starting with 7.8.0 ===<br />
<br />
The OX middleware can be configured via<br />
<br />
com.openexchange.mailmapping.lookUpByDomain=false<br />
<br />
in mailresolver.properties to search for the target email address within the whole local OX installation.<br />
<br />
'''This can have a major impact on performance in bigger installations since every request will search in all existing user databases!'''<br />
<br />
== Custom Mail Resolver ==<br />
<br />
If you have a ''custom authenticaion / login'' system, Guard will need to be configured to access your custom mail Resolver, and your custom system will need to provide the information required for Guard to process the recipient.<br />
<br />
Set the custom URL in the <nowiki>/opt/open-xchange/etc/guard-core.properties</nowiki> file (Guard backend) by adding the setting com.openexchange.guard.mailResolverUrl<br />
<br />
com.openexchange.guard.mailResolverUrl = https://yyyyy.com/resolver/?email= <br />
<br />
Guard will be adding the email address to be resolved at the end of the URL. If the line ends with a ”=”, please include a whitespace after the line for the parser<br />
<br />
Guard will expect a JSON response. If the user is not an OX user, then a blank JSON should be returned ”{}”<br />
<br />
If the user exists, a JSON response should be returned in the following format:<br />
<br />
{<br />
"tester@open-xchange.com":<br />
{"uid":4,"user":<br />
{"language":"en_US","displayName":"Tester, OX"},<br />
"cid":1}<br />
}<br />
<br />
If the user does not exist, a blank JSON should be returned<br />
{}<br />
<br />
Email address should be the identifier, followed by the uid (user id), cid (the context Id), and user data including language and display name.<br />
<br />
''Note:'' If there are multiple OX Backends served by this mail resolver, then only the user information to which Guard has access should be provided. The mailResolver should not provide userid/contextid information for a database that Guard doesn't have access to.<br />
<br />
Most probably, the OX CID is already available in one of your existing LDAP / databases systems, to map your customer/contract-IDs to the corresponding OX AppSuite tenant/context ID. Then you need to lookup the userid + language + displayname of this email address, if its an AppSuite email address.<br />
<br />
<br />
We recommend that you do a loadtest against your custom resolver endpoint. E.g via JMETER + CSV input for random email addresses.<br />
<br />
'''Note:''' A custom mailresolver can also be implemented as an OSGi plugin for the App Suite middleware. Please contact us for more information or an offer for custom implementation.</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=Template:OXLoadBalancingClustering_OXConfiguration&diff=25154Template:OXLoadBalancingClustering OXConfiguration2019-12-06T17:44:34Z<p>Dennis Sieben: /* Configuring Open-Xchange Server */</p>
<hr />
<div>== Configuring Open-Xchange Server ==<br />
Install all relevant Open-Xchange Server packages to both groupware nodes after adding the Open-Xchange software repository to your package manages configuration. Corresponding installation instructions for your distribution can be found here:<br />
<br />
{{#if:{{{release|}}}|<br />
{{#ifeq:{{{release|}}}|6.22|<br />
<br />
* [[Open-Xchange_Installation_Guide_for_Debian_6.0_622|Download and Installation Guide for Debian GNU/Linux 6.0 (Squeeze)]]<br />
* [[Open-Xchange_Installation_Guide_for_SLES11_622|Download and Installation Guide for SUSE Linux Enterprise Server 11]]<br />
* [[Open-Xchange_Installation_Guide_for_RHEL6_622|Download and Installation Guide for RedHat Enterprise Linux 6]]<br />
* [[Open-Xchange Installation Guide for CentOS 6_622|Download and Installation Guide for CentOS 6]]<br />
<br />
|{{#ifeq:{{{release|}}}|appsuite|<br />
<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_6.0|Download and Installation Guide for Debian GNU/Linux 6.0 (Squeeze)]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_7.0|Download and Installation Guide for Debian GNU/Linux 7.0 (Wheezy)]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_SLES11|Download and Installation Guide for SUSE Linux Enterprise Server 11]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_RHEL6|Download and Installation Guide for RedHat Enterprise Linux 6]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_CentOS_6|Download and Installation Guide for CentOS 6]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_CentOS_7|Download and Installation Guide for CentOS 7]]<br />
<br />
}}|}}| {{#!:<br />
<br />
* [[Open-Xchange_Installation_Guide_for_Debian_6.0_622|Download and Installation Guide for Debian GNU/Linux 6.0 (Squeeze)]]<br />
* [[Open-Xchange_Installation_Guide_for_SLES11_622|Download and Installation Guide for SUSE Linux Enterprise Server 11]]<br />
* [[Open-Xchange_Installation_Guide_for_RHEL6_622|Download and Installation Guide for RedHat Enterprise Linux 6]]<br />
* [[Open-Xchange Installation Guide for CentOS 6_622|Download and Installation Guide for CentOS 6]]<br />
<br />
}}}}<br />
<br />
It's also possible to install backend and frontend components on each node. The difference is that a backend only on each node demands separate machines which the fronend in front of the backend nodes, while you only need a load balancer in front of the nodes if you install the backend and the frontend on each node.<br />
<br />
Create the ''configdb'' database at the MySQL Master. This step does only need to be performed on one of the Open-Xchange Server nodes.<br />
$ /opt/open-xchange/sbin/initconfigdb --configdb-user=openexchange --configdb-pass=secret --configdb-host=10.20.30.217<br />
<br />
Setup the Open-Xchange Server configuration. This step needs to be performed on 'both' groupware nodes. Note that the ''--jkroute'' parameter must equal the ''route'' parameter at the web servers ''proxy_ajp'' load balancing configuration of the specific server.<br />
Node 1:<br />
$ /opt/open-xchange/sbin/oxinstaller --servername=oxserver --configdb-readhost=10.20.30.219 --configdb-writehost=10.20.30.217 --configdb-user=openexchange --master-pass=secret --configdb-pass=secret --jkroute=OX1 --ajp-bind-port=*<br />
Node 2:<br />
$ /opt/open-xchange/sbin/oxinstaller --servername=oxserver --configdb-readhost=10.20.30.219 --configdb-writehost=10.20.30.217 --configdb-user=openexchange --master-pass=secret --configdb-pass=secret --jkroute=OX2 --ajp-bind-port=*<br />
<br />
Startup the Open-Xchange Daemon on one of the nodes. Wait some seconds until it is started completely.<br />
$ systemctl start open-xchange<br />
<br />
Now register the Open-Xchange Server at the database. Note that a ''server'' is a whole cluster in this case. This step does only need to be performed on one of the Open-Xchange Server nodes.<br />
$ /opt/open-xchange/sbin/registerserver -n oxserver -A oxadminmaster -P secret<br />
<br />
Register the filestorage. This step does only need to be performed on one of the Open-Xchange Server nodes. Note that the NFS export must be mounted to the same path on both groupware nodes.<br />
$ /opt/open-xchange/sbin/registerfilestore -A oxadminmaster -P secret -t file:///var/opt/filestore<br />
<br />
Now register the MySQL Master database in configdb. This step does only need to be performed on one of the Open-Xchange Server nodes.<br />
$ /opt/open-xchange/sbin/registerdatabase -A oxadminmaster -P secret --name oxdatabase --hostname 10.20.30.217 --dbuser openexchange --dbpasswd secret --master true<br />
database 4 registered<br />
<br />
Check the returned database ID which is 4 in this case. This value is required to register the MySQL Slave database in configdb. This step does only need to be performed on one of the Open-Xchange Server nodes.<br />
$ /opt/open-xchange/sbin/registerdatabase -A oxadminmaster -P secret --name oxdatabase_slave --hostname 10.20.30.219 --dbuser openexchange --dbpasswd secret --master false --masterid=4<br />
<br />
Now start Open-Xchange Server on both groupware nodes.<br />
$ systemctl stop open-xchange<br />
$ systemctl start open-xchange<br />
<br />
<br />
Create a new context and a testuser<br />
$ /opt/open-xchange/sbin/createcontext -A oxadminmaster -P secret -c 1 -u oxadmin -d "Context Admin" -g Admin -s User -p secret -L defaultcontext -e oxadmin@example.com -q 1024 --access-combination-name=all<br />
$ /opt/open-xchange/sbin/createuser -c 1 -A oxadmin -P secret -u testuser -d "Test User" -g Test -s User -p secret -e testuser@example.com<br />
<br />
=== Test Session load balancing ===<br />
Apache is configured to use a 50:50 balancing between both Open-Xchange Servers. Now that they are up and running its time to check if this balancing works. This can be done by simply watching the Open-Xchange Server log files while a user logs in.<br />
Execute ''tail'' to the ''open-xchange.log.0'' file on both servers. Then login with the testuser, one of the servers log file should show something like<br />
$ tail -fn200 /var/log/open-xchange/open-xchange.log.0<br />
[...]<br />
INFO: Session created. ID: 31060fc80b9e44d38148ef4d5d19963d, Context: 1, User: 3<br />
<br />
Then logout and login again. This time, the session should be created on the other server. On the client side, the JSESSIONID cookie at the browser shows evidence on which server the user has logged in by the trailing ".OX-" identifier. This identifier is set by Open-Xchange Server based on its AJP_JVM_ROUTE attribute.</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages&diff=23724AppSuite:UpdatingOXPackages2017-10-18T13:22:05Z<p>Dennis Sieben: </p>
<hr />
<div><div class="title">Updating OX App Suite packages</div><br />
<br />
''Synopsys'': This article describes how to update OX App Suite packages from one service pack to another.<br />
<br />
== Warnings ==<br />
<br />
Before we begin, here are several things that you should keep in mind:<br />
* If you are '''updating a cluster, please do it one node after the other'''. Turn the node off, update, turn it on again, make sure it works in the cluster. Have a look here, too: [[Running_a_cluster#Upgrading_a_single_Node|Upgrading a single node]]<br />
* If you don't have a cluster of OX nodes, then your complete installation needs to be taken down temporarily.<br />
* Please '''update the backend before the frontend'''.<br />
* Please '''do not restart Open-Xchange during the database update'''. A database update can happen after installing minor or major updates. As soon as the first user tries to log in to the system or if any provisioning action is done, this update starts.<br />
<br />
=== Upgrading to 7.8.4 ===<br />
* During the upgrade to 7.8.4 the existing ''JAVA_XTRAOPTS'' configuration property of the middleware stack in the file ''ox-scriptconf.sh'' will automatically be split up and migrated to a new categories approach. Please have a look at [[AppSuite:MiddlewareStartup#Evaluate_JVM_commandline_options|JVM commandline options]] and review the automatically upgraded configuration file.<br />
<br />
== How to get updates? ==<br />
<br />
OX App Suite updates can be accessed by customers with a valid license.<br />
<br />
In addition, you need to configure the [[OXReportClient]].<br />
<br />
= Updating OX App Suite Packages =<br />
<br />
<br />
== Installing Updates ==<br />
<br />
A new service pack usually introduces new packages and requires configuration changes. To get all required new packages and configuration changes, the following '''must''' be done when installing updates.<br />
<br />
(Please, keep the [[#Warning|warning about frontend updates before backend updates]] in mind)<br />
<br />
=== On Debian based distributions ===<br />
<br />
Add the following entry to <tt>/etc/apt/sources.list.d/open-xchange.list</tt><br />
<br />
deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/appsuiteui/updates/DebianJessie/ /<br />
deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/DebianJessie /<br />
Then run<br />
<br />
$ apt-get update<br />
$ apt-get dist-upgrade<br />
<br />
If you want to see, what apt-get is going to do without actually doing it, you can run:<br />
<br />
$ apt-get dist-upgrade -s<br />
<br />
After the new packages are installed, the open-xchange process needs a restart:<br />
<br />
<pre>$ /etc/init.d/open-xchange restart</pre><br />
<br />
=== On RPM based distributions ===<br />
<br />
==== RHEL6/CentOS6 ====<br />
<br />
Add the following entries to <tt>/etc/yum.repos.d/ox.repo</tt>:<br />
<br />
[ox-updates-appsuiteui]<br />
name=Open-Xchange Updates<br />
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/appsuiteui/updates/RHEL6/<br />
gpgkey=http://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
[ox-updates-backend]<br />
name=Open-Xchange Updates<br />
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL6/<br />
gpgkey=http://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
and run<br />
<br />
$ yum update<br />
<br />
$ yum upgrade<br />
<br />
After the new packages are installed, the open-xchange process needs a restart:<br />
<br />
<pre>$ /etc/init.d/open-xchange restart</pre><br />
(Please, keep the [[#Warnings|warning about database updates]] in mind)<br />
<br />
==== RHEL7/CentOS7 ====<br />
<br />
Add the following entries to <tt>/etc/yum.repos.d/ox.repo</tt>:<br />
<br />
[ox-updates-appsuiteui]<br />
name=Open-Xchange Updates<br />
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/appsuiteui/updates/RHEL7/<br />
gpgkey=http://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
[ox-updates-backend]<br />
name=Open-Xchange Updates<br />
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/<br />
gpgkey=http://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
and run<br />
<br />
$ yum update<br />
<br />
$ yum upgrade<br />
<br />
After the new packages are installed, the open-xchange process needs a restart:<br />
<br />
<pre>$ /etc/init.d/open-xchange restart</pre><br />
(Please, keep the [[#Warnings|warning about database updates]] in mind)<br />
<br />
==== SLES12 ====<br />
<br />
Add the updates repository to the repository list:<br />
<br />
$ zypper ar http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/appsuiteui/updates/SLE_12/ OXAPPSUITEUIUPDATES<br />
$ zypper ar http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12/ OXBACKENDUPDATES<br />
<br />
and run<br />
<br />
$ zypper dup -r OXAPPSUITEUIUPDATES<br />
$ zypper dup -r OXBACKENDUPDATES<br />
<br />
You might need to run<br />
<br />
$ zypper ref<br />
<br />
to update the repository metadata before running ''zypper up''.<br />
<br />
After the new packages are installed, the open-xchange process needs a restart:<br />
<br />
<pre>$ rcopen-xchange restart</pre><br />
(Please, keep the [[#Warnings|warning about database updates]] in mind.<br />
<br />
= Updating OX App Suite Packages for older versions =<br />
<br />
<br />
== Installing Updates ==<br />
<br />
A new service pack usually introduces new packages and requires configuration changes. To get all required new packages and configuration changes, the following '''must''' be done when installing updates.<br />
<br />
(Please, keep the [[#Warning|warning about frontend updates before backend updates]] in mind)<br />
<br />
=== On Debian based distributions ===<br />
<br />
If you want to update an older version of Open-Xchange App Suite to the latest maintenance release, add the following entry to <tt>/etc/apt/sources.list.d/open-xchange.list</tt>. Replace VERSION with the version you are using (e.g. 7.6.2). See [[AppSuite:Version_Support_Committment]] for the currently supported versions. Also, make sure that your repository configuration points at the versioned base installation repositories (instead of using the <tt>stable</tt> symlink.)<br />
<br />
deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/DebianWheezy/ /<br />
deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/DebianWheezy/ /<br />
<br />
deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/DebianJessie/ /<br />
deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/DebianJessie /<br />
<br />
Then run<br />
<br />
$ apt-get update<br />
$ apt-get dist-upgrade<br />
<br />
If you want to see, what apt-get is going to do without actually doing it, you can run:<br />
<br />
$ apt-get dist-upgrade -s<br />
<br />
After the new packages are installed, the open-xchange process needs a restart:<br />
<br />
<pre>$ /etc/init.d/open-xchange restart</pre><br />
<br />
=== On RPM based distributions ===<br />
<br />
==== RHEL6/CentOS6 ====<br />
<br />
If you want to update an older version of Open-Xchange App Suite to the latest maintenance release, add the following entry to <tt>/etc/yum.repos.d/ox.repo</tt>. Replace VERSION with the version you are using (e.g. 7.4.2, 7.6.0). See [[AppSuite:Version_Support_Committment]] for the currently supported versions. Also, make sure that your repository configuration points at the versioned base installation repositories (instead of using the <tt>stable</tt> symlink.)<br />
<br />
[ox-updates-appsuiteui]<br />
name=Open-Xchange Updates<br />
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/RHEL6/<br />
gpgkey=http://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
[ox-updates-backend]<br />
name=Open-Xchange Updates<br />
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/RHEL6/<br />
gpgkey=http://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
and run<br />
<br />
$ yum update<br />
<br />
$ yum upgrade<br />
<br />
After the new packages are installed, the open-xchange process needs a restart:<br />
<br />
<pre>$ /etc/init.d/open-xchange restart</pre><br />
(Please, keep the [[#Warnings|warning about database updates]] in mind)<br />
<br />
==== RHEL7/CentOS7 ====<br />
<br />
If you want to update an older version of Open-Xchange App Suite to the latest maintenance release, add the following entry to <tt>/etc/yum.repos.d/ox.repo</tt>. Replace VERSION with the version you are using (e.g. 7.4.2, 7.6.0). See [[AppSuite:Version_Support_Committment]] for the currently supported versions. Also, make sure that your repository configuration points at the versioned base installation repositories (instead of using the <tt>stable</tt> symlink.)<br />
<br />
[ox-updates-appsuiteui]<br />
name=Open-Xchange Updates<br />
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/RHEL7/<br />
gpgkey=http://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
[ox-updates-backend]<br />
name=Open-Xchange Updates<br />
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/RHEL7/<br />
gpgkey=http://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
and run<br />
<br />
$ yum update<br />
<br />
$ yum upgrade<br />
<br />
After the new packages are installed, the open-xchange process needs a restart:<br />
<br />
<pre>$ /etc/init.d/open-xchange restart</pre><br />
(Please, keep the [[#Warnings|warning about database updates]] in mind)<br />
<br />
==== SLES 11 ====<br />
<br />
If you want to update an older version of Open-Xchange App Suite to the latest maintenance release, add the following entry to the repository list. Replace VERSION with the version you are using (e.g. 7.4.2, 7.6.0). See [[AppSuite:Version_Support_Committment]] for the currently supported versions. Also, make sure that your repository configuration points at the versioned base installation repositories (instead of using the <tt>stable</tt> symlink.)<br />
<br />
$ zypper ar http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/SLES11/ OXAPPSUITEUIUPDATES<br />
$ zypper ar http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/SLES11/ OXBACKENDUPDATES<br />
<br />
and run<br />
<br />
$ zypper dup -r OXAPPSUITEUIUPDATES<br />
$ zypper dup -r OXBACKENDUPDATES<br />
<br />
You might need to run<br />
<br />
$ zypper ref<br />
<br />
to update the repository metadata before running ''zypper up''.<br />
<br />
After the new packages are installed, the open-xchange process needs a restart:<br />
<br />
<pre>$ rcopen-xchange restart</pre><br />
(Please, keep the [[#Warnings|warning about database updates]] in mind.<br />
<br />
==== SLES 12 ====<br />
<br />
If you want to update an older version of Open-Xchange App Suite to the latest maintenance release, add the following entry to the repository list. Replace VERSION with the version you are using (e.g. 7.4.2, 7.6.0). See [[AppSuite:Version_Support_Committment]] for the currently supported versions. Also, make sure that your repository configuration points at the versioned base installation repositories (instead of using the <tt>stable</tt> symlink.)<br />
<br />
$ zypper ar http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/SLE_12/ OXAPPSUITEUIUPDATES<br />
$ zypper ar http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/SLE_12/ OXBACKENDUPDATES<br />
<br />
and run<br />
<br />
$ zypper dup -r OXAPPSUITEUIUPDATES<br />
$ zypper dup -r OXBACKENDUPDATES<br />
<br />
You might need to run<br />
<br />
$ zypper ref<br />
<br />
to update the repository metadata before running ''zypper up''.<br />
<br />
After the new packages are installed, the open-xchange process needs a restart:<br />
<br />
<pre>$ rcopen-xchange restart</pre><br />
(Please, keep the [[#Warnings|warning about database updates]] in mind.<br />
<br />
= Updating UI plugins =<br />
<br />
If you update only UI plugins without simultaneously upgrading the core UI packages to a new version, you need to perform an additional step after the update to make the changes visible to users.<br />
<br />
The package <tt>open-xchange-appsuite</tt> contains a timestamp which is different in each version. The JavaScript UI in every user's browser will reload all cached code and data whenever this value changes. Since this value does not change when updating only plugin packages, the value must be changed manually with the following command:<br />
<br />
$ /opt/open-xchange/sbin/touch-appsuite --timestamp=20170101.123400<br />
<br />
If you only have one OX node, the parameter <code>--timestamp</code> can be omitted. It defaults to the current UTC time anyway.<br />
<br />
When updating a cluster, the command must use the same timestamp value on every node. Otherwise, browsers will clear their cache and re-download the entire UI code every time load balancer sends them to a different node (i.e. on almost every login). This is also why the timestamps can't be updated automatically: a node doesn't know which value other nodes will pick, which of them are part of the same update, etc.<br />
<br />
The quickest way to obtain a value for the timestamp parameter is to run the command with the parameter <code>-h</code>. It will then print a help message with the current time as an example. For automation, you can use the output of<br />
<br />
date -u +%Y%m%d.%H%M%S<br />
<br />
Again: this value must be computed once, and then the same value must be used on every node in the cluster.<br />
<br />
This step can be performed on each node separately after each node has been updated, or on all nodes at once after all nodes have been updated. If Apache has its own set of dedicated nodes, the <tt>touch-appsuite</tt> call must be performed on the web server nodes, after all corresponding <tt><plugin>-static</tt> packages have been updated.<br />
<br />
[[Category: OX7]]<br />
[[Category: AppSuite]]<br />
<br />
[[Category: Administrator]]</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Installation_Guide_for_Debian_8.0&diff=22508AppSuite:Open-Xchange Installation Guide for Debian 8.02016-11-08T13:52:37Z<p>Dennis Sieben: </p>
<hr />
<div>{{Version|7.8.0}}<br />
<br />
= OX App Suite on Debian GNU/Linux 8.0 =<br />
<br />
{{QuickInstIntro|release=appsuite}}<br />
<br />
= Requirements =<br />
<br />
* Plain installed Debian GNU/Linux 8.0, no graphical tools required<br />
* A supported Java Virtual Machine ([http://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#Server_Platforms learn more])<br />
* A working internet connection<br />
* vim is not installed by default on Debian. If you want to copy & paste the commands from this article into a shell window, you need to <code>apt-get install vim</code> first.<br />
<br />
{{AddReposDebian|debname=jessie|debnameox=DebianJessie|release=appsuite}}<br />
<br />
= Updating repositories and install packages =<br />
<br />
It is highly recommended to import the Open-Xchange build key to your package systems trusted keyring in order to make sure only Open-Xchange packages with valid signing are installed on the system. Otherwise you'll encounter warnings about untrusted package sources. To import the Open-Xchange buildkey, please refer to this quick guide: [[Importing_OX_Buildkey#Importing_key_into_apt_based_systems|Importing OX Buildkey]].<br />
<br />
Reload the package index. This will download the package descriptions available at the software repositories and will enable the Open-Xchange repository as a valid source for signed packages:<br />
<br />
$ apt-get update<br />
<br />
The following command starts the download and installation process of all required package for Open-Xchange deployment:<br />
<br />
{{OXPackageInstallation|installer=apt-get|mysql=mysql-server|javavendor=sun|release=appsuite}}<br />
<br />
You will be asked multiple times to enter a MySQL password, please do '''not''' enter a password at this point. You should enter a strong MySQL admin password for the user "mysql" after the installation has been finished. See: [http://dev.mysql.com/doc/refman/5.0/en/passwords.html MySQL Reference Manual]<br />
<br />
'''Important:''' Some of the scripts assume you have mysql root access from the command line, therefore the advice of "not" to enter a password. If you do, you may find problems following the instructions provided in this howto.<br />
<br />
{{OXConfiguration|mysqlstart=systemctl start mysql}}<br />
<br />
{{oxinstaller|connector=http}}<br />
<br />
After initializing the configuration, restart the Open-Xchange Administration service by executing:<br />
<br />
$ systemctl restart open-xchange<br />
<br />
{{OXRegister|globaldb=true}}<br />
<br />
= Configure services =<br />
<br />
{{ApacheOXModsDebian|connector=http|extramods=lbmethod_byrequests}}<br />
<br />
{{Template:ApacheAppSuiteConf|connector=http|connectorConf=/etc/apache2/conf-enabled/proxy_http.conf|apacheconf=/etc/apache2/sites-enabled/000-default.conf|docroot=/var/www/html|loadmodule=|syncProxyName=eas_oxcluster}}<br />
<br />
After the configuration is done, restart the Apache webserver<br />
<br />
$ systemctl restart apache2<br />
<br />
== Upgrade from Debian 7 ==<br />
<br />
If you updated from Debian 7 to Debian 8 the proxy_http.conf file is still located in the <tt>conf.d</tt> directory which is not read in Debian 8. So you have to move the file to <tt>conf-available</tt> and execute <tt>a2enconf proxy_http</tt> afterwards.<br />
<br />
{{ContextUserAndLogs}}<br />
<br />
<br />
[[Category: AppSuite]]</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=HAproxy&diff=22419HAproxy2016-09-27T09:05:43Z<p>Dennis Sieben: </p>
<hr />
<div>= HAproxy Loadbalancer =<br />
<br />
== Introduction ==<br />
<br />
Where using a Keepalived based approach for Galera loadbalancing is not feasible, the next alternative is to use HAproxy.<br />
<br />
== System Design ==<br />
<br />
We present a solution where each OX node runs a HAproxy instance. This way we can implement a solution without the need for failover IPs or IP forwarding, which is often the reason why the Keepalived based approach is unavailable.<br />
<br />
We create two HAproxy "listener", one round-robin for the read requests, one active/passive for the write requests.<br />
<br />
== Software Installation ==<br />
<br />
HAproxy should be shipped with the distribution.<br />
<br />
Wheezy note: haproxy is provided in wheezy-backports, see http://haproxy.debian.net/<br />
<br />
Short version:<br />
<br />
echo "deb http://http.debian.net/debian wheezy-backports main" > /etc/apt/sources.list.d/wheezy-backports.list<br />
apt-get update<br />
apt-get -t wheezy-backports install haproxy<br />
<br />
== Configuration ==<br />
<br />
The following is a HAproxy configuration file, assuming the Galera nodes have the IPs 192.168.1.101..103:<br />
<br />
global<br />
log 127.0.0.1 local0<br />
log 127.0.0.1 local1 notice<br />
user haproxy<br />
group haproxy<br />
# this is not recommended by the haproxy authors, but seems to improve performance for me<br />
#nbproc 4<br />
maxconn 256000<br />
spread-checks 5<br />
daemon<br />
stats socket /var/lib/haproxy/stats <br />
<br />
defaults<br />
log global<br />
retries 3<br />
maxconn 256000<br />
timeout connect 60000<br />
timeout client 20m<br />
timeout server 20m<br />
option dontlognull<br />
option redispatch<br />
# the http options are not needed here<br />
# but may be reasonable if you use haproxy also for some OX HTTP proxying<br />
mode http<br />
no option httpclose<br />
<br />
listen mysql-read<br />
bind 127.0.0.1:3306<br />
mode tcp<br />
balance roundrobin<br />
option httpchk<br />
server dav-db1 192.168.1.101:3306 check port 9200 inter 12000 rise 3 fall 3<br />
server dav-db2 192.168.1.102:3306 check port 9200 inter 12000 rise 3 fall 3<br />
server dav-db3 192.168.1.103:3306 check port 9200 inter 12000 rise 3 fall 3<br />
<br />
listen mysql-write<br />
bind 127.0.0.1:3307<br />
mode tcp<br />
balance roundrobin<br />
option httpchk<br />
server dav-db1 192.168.1.101:3306 check port 9200 inter 12000 rise 3 fall 3<br />
server dav-db2 192.168.1.102:3306 check port 9200 inter 12000 rise 3 fall 3 backup<br />
server dav-db3 192.168.1.103:3306 check port 9200 inter 12000 rise 3 fall 3 backup<br />
<br />
#<br />
# can configure a stats interface here, but if you do so,<br />
# change the username / password<br />
#<br />
#listen stats<br />
# bind 0.0.0.0:8080<br />
# mode http<br />
# stats enable<br />
# stats uri /<br />
# stats realm Strictly\ Private<br />
# stats auth user:pass<br />
<br />
You can see we use the httpchk option, which means that haproxy makes http requests to obtain node health. Therefore we need to configure something which answers those requests.<br />
<br />
The Percona Galera packages ship with a script /usr/bin/clustercheck which can be called like <br />
<br />
# /usr/bin/clustercheck <username> <password><br />
HTTP/1.1 200 OK<br />
Content-Type: text/plain<br />
Connection: close<br />
Content-Length: 40<br />
<br />
Percona XtraDB Cluster Node is synced.<br />
# <br />
<br />
They also ship an xinetd service definition. On RHEL/CentOS the service needs to be added to /etc/services.<br />
<br />
You need a user for this service. Create as follows:<br />
<br />
mysql -e 'grant process on *.* to "clustercheck"@"localhost" identified by "<password>";'<br />
<br />
Of course substitute here (and in the following) "<password>" by some reasonable password.<br />
<br />
Then adjust the xinetd configuration:<br />
<br />
# default: on<br />
# description: mysqlchk<br />
service mysqlchk<br />
{<br />
# this is a config for xinetd, place it in /etc/xinetd.d/<br />
disable = no<br />
flags = REUSE<br />
socket_type = stream<br />
port = 9200<br />
wait = no<br />
user = nobody<br />
server = /usr/bin/clustercheck<br />
server_args = clustercheck <password><br />
log_on_failure += USERID<br />
only_from = 0.0.0.0/0<br />
per_source = UNLIMITED<br />
type = UNLISTED<br />
}<br />
#<br />
<br />
'''Note''': Please ensure that you haven't set the <tt>max_load</tt> parameter in the xinetd configuration. This parameter will lead to xinetd not answering any request if the load increases above this value. So the system will be detected a dead even though it actually isn't.<br />
<br />
<br />
== Monitoring ==<br />
<br />
Besided using the Galera check service configured before, you can also speak to the stats socket of haproxy using socat.<br />
<br />
echo "show stat" | socat unix-connect:/var/lib/haproxy/stats stdio<br />
<br />
There are more commands available via this socket to enable / disable servers; see the haproxy documentation for details. (As of writing that documentation could be found here: http://cbonte.github.io/haproxy-dconv/configuration-1.5.html#9.2 that URL seems unstable.)</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=CalDAVClients&diff=20871CalDAVClients2015-11-09T14:44:25Z<p>Dennis Sieben: /* Debug Options */</p>
<hr />
<div>= Open-Xchange Calendar synchronization with CalDAV =<br />
<br />
This site describes how the Open-Xchange server can be accessed via its CalDAV interface after the server has been configured as described in [[Caldav_carddav_Bundles]]. Depending on the used client software, different steps are necessary. Other clients may be configured similarly, but are not officially supported.<br />
<br />
== Mac OS X Calendar ==<br />
<br />
For the Calendar application on Mac OS X 10.9 (Mavericks) and above, a CalDAV account can be configured as follows:<br />
<br />
{| <br />
| [[image:caldav-account4.png|thumb]] || style="width:85%"| <br />
* Click the "+" sign in iCal -> Preferences -> Accounts<br />
* As "Account type" select "CalDAV"<br />
* In the "User name" field enter your username<br />
* In the "Password" field enter your password<br />
* In the "Server address" field enter your server address '''usually with the prefix "dav." and a slash as suffix (e.g. "dav.MYSERVER.TLD/")''' <br />
* Click "Create"<br />
* Click "Continue"<br />
|}<br />
<br />
=== Debug Options ===<br />
You can enable a Debug Menu inside the iCal application which gives you access to advanced debugging and logging options. Please notice that some of these options may increase the size of the log files of your system and/or could also log sensitive data like passwords if enabled. Keep also in mind that any setting changed here will remain active until the setting itself will be reverted or changed again which means that disabling the Debug Menu itself is not sufficient to reset any debug settings to their defaults. All settings are case sensitive.<br />
<br />
Open a terminal window (Applications > Utilities > Terminal) and issue the following command for<br />
* enabling the Debug Menu in iCal:<br />
defaults write com.apple.iCal CDB 1<br />
* disabling the Debug Menu in iCal:<br />
defaults write com.apple.iCal CDB 0<br />
* enabling CalDAV HTTP activity logging:<br />
defaults write com.apple.iCal LogHTTPActivity -boolean TRUE<br />
* disabling CalDAV HTTP activity logging:<br />
defaults write com.apple.iCal LogHTTPActivity -boolean FALSE<br />
<br />
'''Pay attention''': If you change these settings it might be needed to kill the CalendarAgent process with <code>killall CalendarAgent</code> just restarting the MacOS calendar application might not be enough. So in case you won't see any additional log output in the syslog, or the additional log output doesn't vanish after switching off these setting, please try killing the CalendarAgent process.<br />
<br />
== iOS Calendar ==<br />
<br />
The iOS Calendar application on the iPhone, iPod or iPad can be configured as follows.<br />
<br />
{| <br />
| [[image:ios_caldav_config.png|thumb]] || style="width:85%"| <br />
* Open "Settings"<br />
* Select "Mail, Contacts, Calendars" -> "Add Account..." -> "Other" -> "Add CalDAV Account"<br />
* Enter the server address, username as password as shown in the screenshot<br />
* Click "Next"<br />
|}<br />
<br />
== Thunderbird/Lightning ==<br />
''Available since Open-Xchange Server v6.20.7''<br />
<br />
The steps below describe how to setup the Mozilla Thunderbird client with the Lightning Add-on. <br />
<br />
=== Prerequisites ===<br />
Please ensure that the following preconditions are met before continuing:<br />
* Latest versions of the Mozilla Thunderbird E-Mail client and the Lightning Add-on (check https://addons.mozilla.org/thunderbird/addon/lightning/ and http://www.mozilla.org/thunderbird/ for details)<br />
* In the Mozilla Thunderbird client, an E-Mail account for the user's Open-Xchange mailbox needs to be setup before configuring the CalDAV access<br />
<br />
=== Discover the CalDAV URL of your Calendar Folders ===<br />
In contrast to some other clients, Thunderbird/Lightning is not able to discover all the available calendar collections automatically. Instead, each calendar folder needs to be added seperately in the client. To do so, one needs to know the CalDAV URLs of the calendar folder that should be synchronized with the client. This URL is displayed in the properties-page in the Groupware web-interface.<br />
<br />
{| <br />
| [[image:CalDAV_URL_Step1.png|thumb]] || style="width:85%"| <br />
* Open a webbrowser and login to the groupware web-interface<br />
* From the folder tree, open the context menu of a calendar folder and select "Properties"<br />
|-<br />
| [[image:CalDAV_URL_Step2.png|thumb]] ||<br />
* The CalDAV URL is shown in the content area. Note down the URL or copy it to the clipboard.<br />
|}<br />
<br />
=== Add a Calendar in Thunderbird/Lightning ===<br />
As already mentioned, each Calendar folder that should be sychronized has to be added separately in the client. The following steps show how to add a Calendar in Thunderbird/Lightning. Before starting, ensure that the client is connected to the network and the server can be accessed.<br />
<br />
{| <br />
| [[image:LightningSetup_Step1.png|thumb]] || style="width:85%"| <br />
* Select "Events and Tasks" -> "Calendar" from the menu bar to switch to the Calendar view<br />
|-<br />
| [[image:LightningSetup_Step2.png|thumb]] || style="width:85%"| <br />
* From the menu bar, select "File" -> "New" -> "Calendar..."<br />
|-<br />
| [[image:LightningSetup_Step3.png|thumb]] || style="width:85%"| <br />
* In the popup window, select "On the network" and click "Next >"<br />
|-<br />
| [[image:LightningSetup_Step4.png|thumb]] || style="width:85%"| <br />
* As format, select "CalDAV"<br />
* Enter the CalDAV path as reported by the folder's properties page (see above) as location<br />
* For offline access, check the "Cache" checkbox <br />
* Click "Next >" to continue<br />
|-<br />
| [[image:LightningSetup_Step5.png|thumb]] || style="width:85%"| <br />
* Enter a name for the Calendar and assign a color if you like <br />
* Select whether reminders should be shown or not (recommended setting: off, see below for details)<br />
* Select the E-Mail account belonging to the Calendar user from the list <br />
* Click "Next >" to create the Calendar <br />
|-<br />
| [[image:LightningSetup_Step6.png|thumb]] || style="width:85%"| <br />
* When requested, enter your username and password for the server<br />
* Afterwards, the Calendar setup is complete and the contents are synchronized<br />
|}<br />
<br />
=== Debug Options ===<br />
In case of synchronization problems, the built-in error console of Mozilla Thunderbird may provide valuable information. The error console can be opened via "Tools" -> "Error Console". To increase the loglevel of the Lightning Add-on, open the config editor by selecting "Tools" -> "Options..." -> "Advanced" -> "Config Editor..." and set the properties "calendar.debug.log" and "calendar.debug.log.verbose" to "true".<br />
<br />
<br />
== General Limitations ==<br />
Please consider the following known limitations for the CalDAV interface:<br />
<br />
=== Reminders ===<br />
* While the iCalendar standard allows to set appointment reminders past due an appointment's start-date, the OX server is not able to save such alarm times and discards them.<br />
* Multiple reminders in an event are not supported by the OX server and are discarded.<br />
* Only reminders of type "DISPLAY" are supported by the OX server, reminders of other iCal types are discarded.<br />
* When dismissing reminders of recurring appointments in the Mozilla Lightning client, the reminder is removed from the whole recurring appointment object, since it's not possible to determine to which occurrence the dismiss action belongs to.<br />
* On iOS devices, when a custom default alert time is configured via Settings -> Mail, Contacts, Calendars -> Default Alert Times, this setting may also affect appointments you don't participate in. This is a client-specific feature and can't be influenced by the server.<br />
* Due to incompatible handling of reminders in the Mozilla Thunderbird / Lightning client, especially for reminders in recurring appointments, it's recommended to turn off reminders in synchronized calendar folders there (from the context menu of a calendar, select 'Properties' and uncheck 'Show Alarms').<br />
<br />
=== Unsupported Properties ===<br />
* Generally, only those appointment and task properties that are also available on the Open-Xchange server are used for synchronization, i.e. all unsupported properties are ignored and not saved.<br />
* The "URL" property for iCal resources is not supported by the OX server and is discarded.<br />
* Importing or exporting file attachments (property "ATTACH") is not supported via the CalDAV interface.<br />
<br />
=== Private Appointments ===<br />
* Appointments classified as "private" are exported by the server with the "CLASS" property set to "PRIVATE".<br />
* iCal events with the "CLASS" property set to either "CONFIDENTIAL" or "PRIVATE" are treated in the same way by the server and are imported as "private" appointments.<br />
* Since "private" appointments with participants are not supported by the server, saving such an appointment results in the participants being removed implicitly during import.<br />
<br />
=== Tasks ===<br />
* Only simple tasks (no participants, no recurrence) are supported.<br />
* Only tasks from personal folders (no shared or public folders) are supported.<br />
* Only the properties "DTSTART", "DUE", "CATEGORIES", "SUMMARY", "PRIORITY", "DESCRIPTION", "VALARM", "STATUS", "PERCENT-COMPLETE" and "COMPLETED" are synchronized, other ones are discarded by the server.<br />
<br />
===Creating new Collections===<br />
* Creating a new collection in the client results in a new folder being created at the server, with the default calendar or tasks folder as its parent. <br />
* In the Mac OS clients, the name of a new folder may be need to set twice during creation, since the collection's location as chosen by the client changes once after sending it to the server. <br />
* Note: Due to the lacking support of the MKCALENDAR HTTP request in Apache's mod_ajp module, creating new collections currently only works when using the [[Grizzly]] package on the OX server.<br />
<br />
===Permissions in Shared Folders===<br />
* In a Calendar folder that is shared to the CalDAV user by another groupware user, the Mac OS iCal client does not allow editing appointments where the CalDAV user is not the organizer of the appointment, even if sufficient permissions were granted. This is a built-in restriction of the client, however, you are still able to edit or delete such appointments in the groupware web interface.</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=Context_Preprovisioning&diff=20585Context Preprovisioning2015-10-01T09:24:59Z<p>Dennis Sieben: /* Context Preprovisioning */</p>
<hr />
<div>= Context Preprovisioning =<br />
<br />
The standard createcontext call (be it via CLT or RMI or SOAP) is designed to work under all possible cornercases, like concurrent createcontext, createuser, deletecontext, including potential generation and removal of DB schemas and correct counting of schemas on target (DBs, Schemas, Filestores) to allocate the context correctly according to the rules (like weights, etc).<br />
<br />
In order to achieve this, a number of expensive DB queries and extensive locking needs to take place. We optimized this as far as possible while still meeting the "general purupose" requirements outlined above, but it still is costly.<br />
<br />
For other usecases a lot of these queries and locks is not necessary. In particular if it is possible to allocate a "pre-provisioning" phase in an implementation project where only createcontext takes place, and all schemas can be pre-generated, a lot of these allocation queries and locks can be skipped.<br />
<br />
This article is to describe the prerequisites of this "fast mode preprovisioning", and how to execute it.<br />
<br />
== Prerequisites ==<br />
<br />
* All required DB schemas are pre-generated (see below)<br />
* Only createcontext, no other provisioning calls, no HTTP API calls<br />
* Only one provisioning host (which usually does not become the bottleneck; the bottleneck is on the DB usually)<br />
<br />
== Execution ==<br />
<br />
=== Schema pre-generation ===<br />
<br />
To pre-generate schemas, you can temporarily set the setting CONTEXTS_PER_SCHEMA in /opt/open-xchange/etc/plugin/hosting.properties to the value 1. Then, every subsequent createcontext will trigger the generation of a schema. So we recommend to generate the schemas with placeholder contexts which will not actually used for anything, just to generate the schemas, and by not deleting them we make sure the schemas are not teared down also.<br />
<br />
So with this setting CONTEXTS_PER_SCHEMA=1, you create as much contexts as you require for your final number of contexts to be provisioned. Then you change that setting back to its original value (as per system high level design, usually something between 1000 and 7000).<br />
<br />
=== Context Creation in Fast Mode ===<br />
<br />
There are a number of options you need to set to run in "fast mode".<br />
<br />
* In order to save OX from counting contexts per filestore, you should use the --destination-store-id <id> argument to specifiy a target filestore.<br />
* The same reasoning applies to the target database, --destination-database-id <destination-database-id><br />
* Then to use the "fast mode" (skipping locks and some checks) you can use one of the two following. For a discussion see below.<br />
** --schema-name <schema-name><br />
** --schema-strategy=in-memory<br />
<br />
Then, the most important thing is: context creation parallelizes reasonably well at least until the number of DB hosts you got in your setup, perhaps even beyond. So you want to implement some parallel scheme of creating contexts, but with lesser parallelity than the number of schemas you pregenerated. The optimal number of parallel createcontext "streams" depends on your infrastructure and is to be determined heuristically. On single node development machines values up to 10 concurrent streams are reasonable. On larger test platforms (and also on a production platform) we found that up to 100 streams make sense and increase the throughput. But, if increasing the number of streams further does not increase throughput, but only latency, you should reduce the number of streams again.<br />
<br />
To implement parallel streams of createcontext, you can do one of the following:<br />
<br />
* The most simple (and most simple to understand) approach is to create one huge .csv file which is designed to be fed into the CLT createcontext --csv. Then you split that file into a number of chunks which matches the number of parallel streams you want to run. Then you invoke (from a shell script, for example), just the corresponding number of createcontext --csv tools in parallel.<br />
* More sophisticated is to create a program which creates the required data (or reads them from some input) and uses a multithreaded worker model to create the required number of streams<br />
* You can use our [[Gatling_Performance_Tests|gatling tools]] to load-test your system. You will probably need help setting up this stuff, so contact your OX consultant for assistance.<br />
<br />
==== Schema-Name vs Schema-Strategy ====<br />
<br />
These are two different implementations with the same goal to run in "fast mode", skipping locks and some checks.<br />
<br />
The approach of the --schema-name method is to require the caller to do book-keeping of how many contexts are allocated where. Usually some simple round-robin approach is sufficient here. But be aware that the schema names you supply must match the DB ID you supply. So usually you have a tool which creates the createcontext requests, and this tool needs to be coded such that the schema names it gives are valid for the given DB ID.<br />
<br />
The approach of the --schema-strategy=in-memory is to not require any logic from the caller, but rather do the required book-keeping in memory of OX.<br />
<br />
Both approaches seem to work in our benchmarks with similar achieved throughput. None of them have undergone extensive real-world usage. Theoretically the in-memory approach is easier to integrate into existing workflows, but the schema-name approach is much simpler inside of OX ant potentially more robust.</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=HTTP_API_MailFilter&diff=18177HTTP API MailFilter2014-07-29T11:53:30Z<p>Dennis Sieben: /* The core */</p>
<hr />
<div><center>'''Open-Xchange Mail Filter HTTP API'''</center><br />
<br />
= Introduction =<br />
This document describes only the mail filter HTTP-API. So it's only a part which must be embedded into something which counts for login/logout, session handling and low-level protocol issues such as error handling. At the moment this will be the groupware server. So the modules needed for basic operations can be found there.<br />
<br />
= Module mailfilter =<br />
This module is used to access all mail filter related options.<br />
<br />
First of all the main structure of a mail filter script is, that it has different rules. Each of them contains one command. This command takes a test condition which executes the actions given in that command if the test condition is true.<br />
<br />
The test condition consists of a test command and some arguments for this command depending on the command itself. Because the available tests depend on the mail filter server, these tests must be determined at runtime. So that no test field is transferred to the server which it isn't able to handle. Examples for tests are <tt>address</tt>, <tt>allof</tt> and <tt>anyof</tt>.<br />
<br />
Each test has a special comparison. The list of available comparisons depends on the test given and the mail filter server configuration so they have to be determined at runtime too.<br />
<br />
Each time you want to do some action on a mail you need a so called action command. This describes what to do with a mail. To action commands the same applies as to the test commands and their comparison types, they must be determined at runtime.<br />
<br />
All those dynamical values can be fetched via a config object at startup. This object shows the capabilities of the server to the client. This allows the client to show only the capabilities the server actually has to the user and to send only objects to the server which produce no errors on the server side.<br />
<br />
To deal with this high flexibility of mail filters this specification can be roughly divided into 2 parts. A non-changing core and dynamical extensions. The core specification is that each rule consists of a name, an ID, a value showing if this rule is active or not and a tag which can be set on a rule to mark that rule for a special purpose. Furthermore each rule takes a test object, specifying in what case the following actions are triggered, and one or many actioncommands, specifying the actions itself. For a detailed specification see [[#Table 1|Table 1]].<br />
<br />
The objects for the tests and the actions are dynamical, so the set presented in this specification may be changed over the time, but only compatible changes are allowed to the objects, otherwise new test or action objects have to be introduced. Due to the fact that not every sieve implementation will offer all the capabilities written in this document, the server will sent his configuration if a special request is made. This configuration will show which of the tests and which of the actions are allowed. So for example if the server signals that it is capable of handling vacation, sending a vacation object as action is safe.<br />
<br />
Furthermore some tests use a comparison field as stated above which specifies how the fields are compared. The values of this field must also be determined at runtime. So in the configuration object there is a special part which shows the comparisons which are available. Note that not all comparisons can be used with every test. Some of them are denoted to a special test, which can be found in the [[#Table 3|Table 3]].<br />
<br />
= The core =<br />
As written in the introduction the main part of a mail filter are the rules. A rule object will always have the structure you can see in the table below ([[#Table 1|Table 1]]). The dynamical parts are the test, which are represented by different options, see [[#Tests|4.1. Tests]], and the actions, also represented in [[#Actions|4.2. Actions]]. Note that the test and actioncmds fields and the text and errormsg fields are mutual exclusive. So if test and actioncmds fields are filled the text and errormsg fields are not present and vice versa.<br />
<br />
{| id="Table 1" cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| Integer<br />
| <br />
| A unique identifier (once created must not be changed)<br />
<br />
|-<br />
| position<br />
| Integer<br />
| <br />
| The position inside the mail filter list. Starts with 0<br />
<br />
|-<br />
| rulename<br />
| String<br />
| <br />
| A name describing the rule, can be empty but must not contain a line break<br />
<br />
|-<br />
| active<br />
| Boolean<br />
| <br />
| If this rule is active or not<br />
<br />
|-<br />
| flags<br />
| Array<br />
| <br />
| A string array containing flags which are set on this rule. Each flag can only contain the following characters: 1-9 a-z A-Z. Currently 3 flags are reserved here: "spam" which marks the default spam rule, "vacation" which marks the vacation rules and "autoforward" which marks an autoforwarding rule.<br />
<br />
|-<br />
| test<br />
| Object<br />
| <br />
| The structure of the different test objects can be found in section [[#Tests|4.1. Tests]]. The valid tests in the current setup can be found in the configuration object <br />
<br />
|-<br />
| actioncmds<br />
| Array<br />
| <br />
| An array of action objects whose different structures can be found in section [[#Actions|4.2. Actions]]. The action commands which are valid here can be determined through the config object see Table 24<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| If this rule cannot be read in this string is filled containing the whole lines of this command.<br />
<br />
|-<br />
| errormsg<br />
| String<br />
| <br />
| If this rule cannot be read in this string is filled containing a message why, or what part of the rule isn't known<br />
<br />
|}<br />
<center>''Table 1: Structure of a rule''</center><br />
<br />
= The dynamical part =<br />
== Tests ==<br />
In this section you will find the structures of all test commands which are specified until now. First a complete list of all test commands is given with a short description of them, afterwards a complete list of all comparison as they belong to the test section. Finally the different objects for those test commands are specified.<br />
<br />
<br />
{| id="Table 2" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| address<br />
| This test type applies to addresses only. So it may be used for all header fields which contain addresses. This test returns true if any combination of the header-list and values-list arguments match.<br />
<br />
|-<br />
| envelope<br />
| This test applies to the envelope of a mail. This test isn't used under normal circumstances as the envelope isn't accessible in all mail setups. This test returns true if any combination of the header-list and values-list arguments match'''.'''<br />
<br />
|-<br />
| true<br />
| A test for a true result (can be used if an action command should be executed every time)'''.'''<br />
<br />
|-<br />
| not<br />
| Negates a given test'''.'''<br />
<br />
|-<br />
| size<br />
| Deals with the size of the mail'''.'''<br />
<br />
|-<br />
| currentdate<br />
| Compares a given date with the current date ('''available with 6.20''')<br />
<br />
|-<br />
| header<br />
| Tests against all headers of a mail. So with this test in contrast to the address test also fields such as subject can be handled. This test returns true if any combination of the header-list and values-list arguments match.<br />
<br />
|-<br />
| body<br />
| Tests against the content of a mail.<br />
<br />
|-<br />
| allof<br />
| Defines an AND condition between several tests'''.'''<br />
<br />
|-<br />
| anyof<br />
| Defines an OR condition between several tests'''.'''<br />
<br />
|}<br />
<center>''Table 2: List of all possible tests''</center><br />
<br />
<br />
{| id="Table 3" cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| is<br />
| If a field is equal to a given value<br />
<br />
|-<br />
| contains<br />
| If a field contains a given value at any position<br />
<br />
|-<br />
| matches<br />
| Tests if the value matches the value in the specified field. Here some wild cards can be used. "*" matches zero or more characters, and "?" matches a single character. To use the characters themselves they have to be escaped via a backslash.<br />
<br />
|-<br />
| regex<br />
| Tests if a given regular expression matches with the value present in the specified field.<br />
<br />
|-<br />
| user<br />
| Tests if the user part of an e-mail address is the value given here. This means in [mailto:herbert+mustermann@example.com herbert+mustermann@example.com]. The user checks the part herbert.<br />
<br />
'''Attention: '''This comparison can only be used in conjunction with the address test<br />
<br />
|-<br />
| detail<br />
| Tests if the detail part of an e-mail address is the value given here. In the example above this evaluates to mustermann.<br />
<br />
'''Attention: '''This comparison can only be used in conjunction with the address test<br />
<br />
|}<br />
<center>''Table 3: List of all possible comparisons''</center><br />
<br />
<br />
<br />
{| id="Table 4" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| address<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see [[#Table 26|Table 26]]).<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields. The test will be true if any of the strings matches<br />
<br />
|}<br />
<center>''Table 4: Structure of address-test''</center><br />
<br />
<br />
{| id="Table 5" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| envelope<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see [[#Table 26|Table 26]]).<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields. The test will be true if any of the strings matches<br />
<br />
|}<br />
<center>''Table 5: Structure of envelope-test''</center><br />
<br />
<br />
{| id="Table 6" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| true<br />
| A string describing the test command.<br />
<br />
|}<br />
<center>''Table 6: Structure of true-test''</center><br />
<br />
<br />
{| id="Table 7" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| not<br />
| A string describing the test command.<br />
<br />
|-<br />
| test<br />
| Object<br />
| <br />
| One of the test objects which result will be negated<br />
<br />
|}<br />
<center>''Table 7: Structure of not-test''</center><br />
<br />
<br />
{| id="Table 8" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| size<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Only two types are valid here. A description can be found in [[#Table 9|Table 9]].<br />
<br />
|-<br />
| size<br />
| Number<br />
| <br />
| A number specifying the size for this comparison, in bytes.<br />
<br />
|}<br />
<center>''Table 8: Structure of size-test''</center><br />
<br />
<br />
{| id="Table 9" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| over<br />
| Used in the size test to check for a value greater than the given one<br />
<br />
|-<br />
| under<br />
| Used in the size test to check for a value less than the given one<br />
<br />
|}<br />
<center>''Table 9: Types of comparison for size''</center><br />
<br />
<br />
<br />
{| id="currentdate" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| currentdate<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Only three types are valid here. A description can be found in [[#Table 11|Table 11]].<br />
<br />
|-<br />
| datepart<br />
| String<br />
| <br />
| A string containing the string "date" as we only allow fix date comparisions for now.<br />
<br />
|-<br />
| datevalue<br />
| Array<br />
| <br />
| A value array containing the corresponding value to the datepart. For "date" this will be an array of "Date". The test will be true if any of the values matches<br />
<br />
|}<br />
<center>''Table 10: Structure of currentdate-test''</center><br />
<br />
<br />
<br />
{| id="Table 11" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| is<br />
| Used in the date test to check for a value equal to the given one<br />
<br />
|-<br />
| ge<br />
| Used in the date test to check for a value greater or equal to the given one<br />
<br />
|-<br />
| le<br />
| Used in the date test to check for a value less or equal to the given one<br />
<br />
|}<br />
<center>''Table 11: Types of comparison for currentdate''</center><br />
<br />
<br />
<br />
{| id="Table 12" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| header<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see [[#Table 26|Table 26]])<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the values for the header fields. The test will be true if any of the strings matches<br />
<br />
|}<br />
<center>''Table 12: Structure of header-test''</center><br />
<br />
<br />
{| id="Table 13" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| body<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see [[#Table 26|Table 26]]).<br />
<br />
|-<br />
| extensionskey<br />
| String<br />
| <br />
| The extension key can be one of the value found in [[#Table 12|Table 12]]<br />
<br />
|-<br />
| extensionsvalue<br />
| String<br />
| <br />
| A value for the given key. If the key has no value (see [[#Table 12|Table 12]] for this information) the value given here is ignored<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the values for the body. The test will be true if any of the strings matches<br />
<br />
|}<br />
<center>''Table 13: Structure of body-test''</center><br />
<br />
<br />
{| id="Table 14" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| content<br />
| An extension used in conjunction with the body test to define the content which should be considered. This extension will need a parameter specifying the mime-type of the part of the message which will be searched.<br />
<br />
|-<br />
| text<br />
| An extension used in conjunction with the body test to define that only the text of the body should be considered in this test. This extension takes no parameter<br />
<br />
|}<br />
<center>''Table 14: List of possible extensions''</center><br />
<br />
<br />
{| id="Table 15" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| allof<br />
| A string describing the test command.<br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| A array of tests<br />
<br />
|}<br />
<center>''Table 15: Structure of allof-test''</center><br />
<br />
<br />
{| id="Table 16" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| anyof<br />
| A string describing the test command.<br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| A array of tests<br />
<br />
|}<br />
<center>''Table 16: Structure of anyof-test''</center><br />
<br />
== Actions ==<br />
In this section you will find the structures of all action commands which are specified until now. First a complete list of all action commands is given with a short description of them, later on the different objects for those commands are specified.<br />
<br />
<br />
{| id="Table 17" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| keep<br />
| Keeps a mail non changed<br />
<br />
|-<br />
| discard<br />
| Discards a mail without any processing<br />
<br />
|-<br />
| redirect<br />
| Redirects a mail to a given e-mail address<br />
<br />
|-<br />
| move<br />
| Moves a mail into a given subfolder. The syntax for the subfolder given here. Must be the correct syntax of the underlying IMAP-server. So it is up to the GUI to detect things such as altnamespace or unixhierarchysep.<br />
<br />
|-<br />
| reject<br />
| Rejects the mail with a given text<br />
<br />
|-<br />
| stop<br />
| Stops any further progressing of a mail<br />
<br />
|-<br />
| vacation<br />
| Creates a vacation mail<br />
<br />
|-<br />
| addflags<br />
| Adds flags to a mail<br />
<br />
|-<br />
| notify<br />
| adds a notification<br />
<br />
|-<br />
| pgp<br />
| encrypts a mail via pgp<br />
<br />
|}<br />
<center>''Table 17: List of possible action commands''</center><br />
<br />
<br />
{| id="Table 18" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| keep<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 18: Structure of keep-command''</center><br />
<br />
<br />
{| id="Table 19" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| discard<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 19: Structure of discard-command''</center><br />
<br />
<br />
{| id="Table 20" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| redirect<br />
| A string defining the object itself<br />
<br />
|-<br />
| to<br />
| String<br />
| <br />
| A string containing where the mail should be redirected to<br />
<br />
|}<br />
<center>''Table 20: Structure of redirect-command''</center><br />
<br />
<br />
{| id="Table 21" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| move<br />
| A string defining the object itself<br />
<br />
|-<br />
| into<br />
| String<br />
| <br />
| This string takes the object id of the destination mail folder as specified in the HTTP API of the groupware<br />
<br />
|}<br />
<center>''Table 21: Structure of move-command''</center><br />
<br />
<br />
{| id="Table 22" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| reject<br />
| A string defining the object itself<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| A string containing the reason why the mail is rejected<br />
<br />
|}<br />
<center>''Table 22: Structure of reject-command''</center><br />
<br />
<br />
{| id="Table 23" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| stop<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 23: Structure of stop-command''</center><br />
<br />
<br />
{| id="Table 24" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| vacation<br />
| A string defining the object itself<br />
<br />
|-<br />
| days<br />
| Integer<br />
| <br />
| The days for which a vacation text is returned<br />
<br />
|-<br />
| addresses<br />
| Array<br />
| <br />
| The addresses for which this vacation is responsible. That means for which addresses out of the aliases array of the user defining this filter, vacations will be sent.<br />
<br />
|-<br />
| subject<br />
| String<br />
| <br />
| The new subject for the returned message (can be left empty, when only adding RE:)<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| The vacation text itself<br />
<br />
|}<br />
<center>''Table 24: Structure of vacation-command''</center><br />
<br />
<br />
{| id="Table 25" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| addflags<br />
| A string defining the object itself<br />
<br />
|-<br />
| flags<br />
| Array<br />
| <br />
| An array containing the flags which should be added to that mail. A flag can be either a system flag or a user flag. System flags begin with a backslash (\) and can be one of the following:<br />
* \seen<br />
* \answered<br />
* \flagged<br />
* \deleted<br />
* \draft<br />
* \recent<br />
System flags are case-insensitive.<br />
<br />
User flags begin with a dollar sign ($) and can contain any ASCII characters between 0x21 (!) and 0x7E (~), inclusive, except for the characters 0x22, 0x25, 0x28, 0x29, 0x2A, 0x5C, 0x5D and 0x7B, which correspond to<br />
"%()*\]{<br />
Mail color flags as used by OX are implemented by user flags of the form $cl_''n'', where ''n'' is a number between 1 and 10, includive.<br />
<br />
See RFC 3501 for further details on IMAP flags and their meanings.<br />
|}<br />
<center>''Table 25: Structure of addflags-command''</center><br />
<br />
{| id="Table 26" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| notify<br />
| A string defining the object itself<br />
<br />
|-<br />
| message<br />
| String<br />
| <br />
| the content of the notification message<br />
<br />
|-<br />
| method<br />
| String<br />
| <br />
| the method of the notification message, e.g. <pre>"mailto:012345678@sms.gateway"</pre><br />
<br />
|}<br />
<center>''Table 26: Structure of notify-command''</center><br />
<br />
{| id="Table 27" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| pgp<br />
| A string defining the object itself<br />
<br />
|-<br />
| keys<br />
| Array<br />
| <br />
| The public keys as string which should be used for encryption<br />
<br />
|}<br />
<center>''Table 27: Structure of pgp-command''</center><br />
<br />
= Requests =<br />
== Get the configuration of the mail filter backend ==<br />
<tt>GET /ajax/mailfilter?action=config</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Response body: An object describing the configuration like described in [[#Table 28|Table 28]].<br />
<br />
<br />
{| id="Table 28" cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| An array containing test-objects like described in [[#Table 29|Table 29]]<br />
<br />
|-<br />
| actioncommands<br />
| Array<br />
| <br />
| An array containing the valid action commands as strings. A list of all possible values can be found in [[#Table 17|Table 17]].<br />
<br />
|}<br />
<center>''Table 28: Config object''</center><br />
<br />
<br />
{| id="Table 29" cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| test<br />
| String<br />
| <br />
| A name for the test. A list of all possible tests can be found in [[#Table 2|Table 2]]. The corresponding objects can be used in the test field in [[#Table 1|Table 1]].<br />
<br />
|-<br />
| comparison<br />
| Array<br />
| <br />
| A string array containing the valid comparison types for this test. Possible values are given in [[#Table 3|Table 3]]. Values given in this array can be used in the comparison field in <br />
<br />
|}<br />
<center>''Table 29: Test object''</center><br />
<br />
== Get all mail filter rules ==<br />
<tt>GET /ajax/mailfilter?action=list</tt><br />
<br />
Parameters:<br />
<br />
* <tt>flag</tt> If given, only rules with this flag are returned<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Response body: An array of rule objects like described in [[#Table 1|Table 1]].<br />
<br />
== Create a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=new</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Request body: Rule object as described in [[#Table 1|Table 1]]. If the field <tt>position</tt> is included in [[#Table 1|Table 1]] it's taken as the position of the rule in the array on the server side. Note that this value shouldn't be greater than the size of all rules<br />
<br />
Response body: An integer for the id of the new created rule.<br />
<br />
== Delete a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=delete</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Request body: An object with the field <tt>id</tt>.<br />
<br />
== Reorder mail filter rules ==<br />
PUT <tt>/ajax/mailfilter?action=reorder</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Request body: An array of unique ids which represents how the rule with the corresponding unique ids are ordered<br />
<br />
== Update a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=update</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Request body: Rule object as described in [[#Table 1|Table 1]] with the <tt>id</tt> set (which identifies the rule to change). Only modified fields are present.<br />
<br />
== Delete the whole script ==<br />
PUT <tt>/ajax/mailfilter?action=deletescript</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Note that this call is only used as workaround for parsing errors in the backend, so that the user is able to kick a whole script if it contains errors in the grammar.<br />
<br />
== Get the whole script ==<br />
PUT <tt>/ajax/mailfilter?action=getscript</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Response body: A text of the complete sieve script<br />
<br />
Note that this call is only used as workaround for parsing errors in the backend, so that the user is able to get the plaintext of a complete script.</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=Mobileconfig_Bundle&diff=17800Mobileconfig Bundle2014-06-12T11:41:07Z<p>Dennis Sieben: </p>
<hr />
<div>= Open-Xchange mobile configuration module =<br />
<br />
== Introduction ==<br />
The Open-Xchange mobile configuration module provides the ability to configure mobile devices for Open-Xchange usage. Currently iPhone, iPad and Windows Mobile are supported.<br />
<br />
To configure a device. The device must be navigated to the URL where the mobile configuration servlet is listening (by default /servlet/mobileconfig). In addition to this URL the login of the user which should be configured on the device must be added as GET parameter "l". So a full URL should look like this:<br />
<br />
https://myhost.com/servlet/mobileconfig?l=testuer%40myhost.com<br />
<br />
Please note that the parameter must be URL encoded, thus @ is written as %40.<br />
<br />
This way the string given in the login parameter will be splitted according to the EAS setting (by default $USER@$DOMAIN), so in the example above the username would be testuer and the domain myhost.com. The email address in this scenario is assumed to be the same like the login. If you have a different setup you can provide a different email addresse with the "m" parameter set.<br />
<br />
It's also possible to pass only a user name without a context. This is done by omitting the separator character. If no context is found the contextname "defaultcontext" is used internally as in many other parts of the product.<br />
<br />
=== Configuration settings ===<br />
<br />
The bundle can be configured at two points, on the one hand the configuration file mobileconfig.properties in the groupware configuration path, and on the other hand the template files which are used for configuration (by default /opt/open-xchange/templates/).<br />
<br />
Most of the setting in the configuration file should be self-explanatory, but two part might be explained in more detail. First the RegEx setting for the mobile device and second the sign part.<br />
<br />
The RegEx settings are used for the detection of the device, therefor the user-agent header send by the device must match the RegEx specified in the configuration file. Most of the time there should be no need to change these setting. But if you have special devices which aren't detected correctly you should consider changing these values. If the detection went wrong, a line with the not-detected header is printed to the log file.<br />
<br />
The signing part is only needed for iPhone/iPad Configuration it doesn't influence Windows Mobile. With these settings the configuration file will be signed before sending, This way you won't get warnings if you install the profile on the iPhone/iPad, but it requires a key and a certificate with a valid CA known by the iPhone/iPad.<br />
<br />
IMPORTANT: To change the URL which is used in the templates, you have to edit /opt/open-xchange/etc/groupware/mobilityconfiguration.properties and edit the URL properly.<br />
<br />
==== Templates ====<br />
<br />
The configuration files send to the mobile devices can be adjusted to your special need through templates. The iPhone configuration is generated from /opt/open-xchange/templates/iPhoneTemplate.tmpl and the Windows Mobile configuration is generated from /opt/open-xchange/templates/winMobileTemplate.tmpl. These templates are process by [http://freemarker.org/ FreeMarker] so you are able to use all function and methods FreeMarker offers. In addition 4 variables are passed to the template files:<br />
<br />
# host - the full qualified hostname for the current webserver (should be the same as the EAS installation)<br />
# domain - the domain (will be a splitted part of the login according to the EAS setting)<br />
# username - the username (will be a splitted part of the login according to the EAS setting)<br />
# email - the email (either the same as the login, or the same like the mail parameter if given)<br />
<br />
'''Note:''' The iPhone template can be changed using the [http://www.apple.com/support/iphone/enterprise Apple Configuration Utility]. Using that tool you can e.g. change the homescreen icon which is provisioned. Furthermore a reference documentation can be found [http://developer.apple.com/library/ios/#featuredarticles/iPhoneConfigurationProfileRef/Introduction/Introduction.html here]. The same applies to the Windows Mobile template.<br />
<br />
{{InstallPlugin|pluginname=open-xchange-mobile-configuration-generator|sopath=updates}}<br />
<br />
{{InstallPlugin|pluginname=open-xchange-eas-provisioning|sopath=6.22/updates/backend|version=v6.22.x}}</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=Mobileconfig_Bundle&diff=17797Mobileconfig Bundle2014-06-12T09:11:10Z<p>Dennis Sieben: </p>
<hr />
<div>= Open-Xchange mobile configuration module =<br />
<br />
== Introduction ==<br />
The Open-Xchange mobile configuration module provides the ability to configure mobile devices for Open-Xchange usage. Currently iPhone, iPad and Windows Mobile are supported.<br />
<br />
To configure a device. The device must be navigated to the URL where the mobile configuration servlet is listening (by default /servlet/mobileconfig). In addition to this URL the login of the user which should be configured on the device must be added as GET parameter "l". So a full URL should look like this:<br />
<br />
https://myhost.com/servlet/mobileconfig?l=testuer%40myhost.com<br />
<br />
Please note that the parameter must be URL encoded, thus @ is written as %40.<br />
<br />
This way the string given in the login parameter will be splitted according to the EAS setting (by default $USER@$DOMAIN), so in the example above the username would be testuer and the domain myhost.com. The email address in this scenario is assumed to be the same like the login. If you have a different setup you can provide a different email addresse with the "m" parameter set.<br />
<br />
It's also possible to pass only a user name without a context. This is done by omitting the separator character. If no context is found the contextname "defaultcontext" is used internally as in many other parts of the product.<br />
<br />
=== Configuration settings ===<br />
<br />
The bundle can be configured at two points, on the one hand the configuration file mobileconfig.properties in the groupware configuration path, and on the other hand the template files which are used for configuration (by default /opt/open-xchange/templates/).<br />
<br />
Most of the setting in the configuration file should be self-explanatory, but two part might be explained in more detail. First the RegEx setting for the mobile device and second the sign part.<br />
<br />
The RegEx settings are used for the detection of the device, therefor the user-agent header send by the device must match the RegEx specified in the configuration file. Most of the time there should be no need to change these setting. But if you have special devices which aren't detected correctly you should consider changing these values. If the detection went wrong, a line with the not-detected header is printed to the log file.<br />
<br />
The signing part is only needed for iPhone/iPad Configuration it doesn't influence Windows Mobile. With these settings the configuration file will be signed before sending, This way you won't get warnings if you install the profile on the iPhone/iPad, but it requires a key and a certificate with a valid CA known by the iPhone/iPad.<br />
<br />
IMPORTANT: To change the URL which is used in the templates, you have to edit /opt/open-xchange/etc/groupware/mobilityconfiguration.properties and edit the URL properly.<br />
<br />
==== Templates ====<br />
<br />
The configuration files send to the mobile devices can be adjusted to your special need through templates. The iPhone configuration is generated from /opt/open-xchange/templates/iPhoneTemplate.tmpl and the Windows Mobile configuration is generated from /opt/open-xchange/templates/winMobileTemplate.tmpl. These templates are process by [http://freemarker.org/ FreeMarker] so you are able to use all function and methods FreeMarker offers. In addition 4 variables are passed to the template files:<br />
<br />
# host - the full qualified hostname for the current webserver (should be the same as the EAS installation)<br />
# domain - the domain (will be a splitted part of the login according to the EAS setting)<br />
# username - the username (will be a splitted part of the login according to the EAS setting)<br />
# email - the email (either the same as the login, or the same like the mail parameter if given)<br />
<br />
'''Note:''' The iPhone template can be changed using the [http://www.apple.com/support/iphone/enterprise Apple Configuration Utility]. Using that tool you can e.g. change the homescreen icon which is provisioned. Furthermore a reference documentation can be found [http://developer.apple.com/library/ios/#featuredarticles/iPhoneConfigurationProfileRef/Introduction/Introduction.html here]. The same applies to the Windows Mobile template.<br />
<br />
{{InstallPlugin|pluginname=open-xchange-mobile-configuration-generator|sopath=updates}}<br />
<br />
{{InstallPlugin|pluginname=open-xchange-mobile-config|sopath=6.22/updates/backend|version=v6.22.x}}</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=Mobileconfig_Bundle&diff=17796Mobileconfig Bundle2014-06-12T09:02:54Z<p>Dennis Sieben: </p>
<hr />
<div>= Open-Xchange mobile configuration module =<br />
<br />
== Introduction ==<br />
The Open-Xchange mobile configuration module provides the ability to configure mobile devices for Open-Xchange usage. Currently iPhone, iPad and Windows Mobile are supported.<br />
<br />
To configure a device. The device must be navigated to the URL where the mobile configuration servlet is listening (by default /servlet/mobileconfig). In addition to this URL the login of the user which should be configured on the device must be added as GET parameter "l". So a full URL should look like this:<br />
<br />
https://myhost.com/servlet/mobileconfig?l=testuer%40myhost.com<br />
<br />
Please note that the parameter must be URL encoded, thus @ is written as %40.<br />
<br />
This way the string given in the login parameter will be splitted according to the EAS setting (by default $USER@$DOMAIN), so in the example above the username would be testuer and the domain myhost.com. The email address in this scenario is assumed to be the same like the login. If you have a different setup you can provide a different email addresse with the "m" parameter set.<br />
<br />
It's also possible to pass only a user name without a context. This is done by omitting the separator character. If no context is found the contextname "defaultcontext" is used internally as in many other parts of the product.<br />
<br />
=== Configuration settings ===<br />
<br />
The bundle can be configured at two points, on the one hand the configuration file mobileconfig.properties in the groupware configuration path, and on the other hand the template files which are used for configuration (by default /opt/open-xchange/templates/).<br />
<br />
Most of the setting in the configuration file should be self-explanatory, but two part might be explained in more detail. First the RegEx setting for the mobile device and second the sign part.<br />
<br />
The RegEx settings are used for the detection of the device, therefor the user-agent header send by the device must match the RegEx specified in the configuration file. Most of the time there should be no need to change these setting. But if you have special devices which aren't detected correctly you should consider changing these values. If the detection went wrong, a line with the not-detected header is printed to the log file.<br />
<br />
The signing part is only needed for iPhone/iPad Configuration it doesn't influence Windows Mobile. With these settings the configuration file will be signed before sending, This way you won't get warnings if you install the profile on the iPhone/iPad, but it requires a key and a certificate with a valid CA known by the iPhone/iPad.<br />
<br />
IMPORTANT: To change the URL which is used in the templates, you have to edit /opt/open-xchange/etc/groupware/mobilityconfiguration.properties and edit the URL properly.<br />
<br />
==== Templates ====<br />
<br />
The configuration files send to the mobile devices can be adjusted to your special need through templates. The iPhone configuration is generated from /opt/open-xchange/templates/iPhoneTemplate.tmpl and the Windows Mobile configuration is generated from /opt/open-xchange/templates/winMobileTemplate.tmpl. These templates are process by [http://freemarker.org/ FreeMarker] so you are able to use all function and methods FreeMarker offers. In addition 4 variables are passed to the template files:<br />
<br />
# host - the full qualified hostname for the current webserver (should be the same as the EAS installation)<br />
# domain - the domain (will be a splitted part of the login according to the EAS setting)<br />
# username - the username (will be a splitted part of the login according to the EAS setting)<br />
# email - the email (either the same as the login, or the same like the mail parameter if given)<br />
<br />
'''Note:''' The iPhone template can be changed using the [http://www.apple.com/support/iphone/enterprise Apple Configuration Utility]. Using that tool you can e.g. change the homescreen icon which is provisioned. Furthermore a reference documentation can be found [http://developer.apple.com/library/ios/#featuredarticles/iPhoneConfigurationProfileRef/Introduction/Introduction.html here]. The same applies to the Windows Mobile template.<br />
<br />
{{InstallPlugin|pluginname=open-xchange-mobile-configuration-generator|sopath=updates}}<br />
<br />
{{InstallPlugin|pluginname=open-xchange-mobile-configuration-generator|sopath=6.22/updates/backend|version=v6.22.x}}</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=Login_variations&diff=17370Login variations2014-04-04T12:37:25Z<p>Dennis Sieben: /* Access via web browser with user credentials */</p>
<hr />
<div><div class="title">Login variations</div><br />
<br />
'''Introduction:''' This paper describes Open-Xchanges's authentication and session handling. It gives an overview of all available mechanisms and on how to safely pass on sessions from external applications to the Open-Xchange Server (Single Sign On, SSO).<br />
<br />
== Overview ==<br />
The Open-Xchange Server web front-end is implemented in AJAX (Asynchronous JavaScript and XML). Thus the complete user interface (GUI) is running in a browser. Opposed to standard web applications there are no HTML pages generated and delivered by the browser.<br />
<br />
The complete user front-end is rendered and displayed in the browser. Based on HTTP/S the data are exchanged with the server via JavaScript Object Notation (JSON). That means it is not possible to simulate front-end actions via HTTP/S request by simulating respectively formatted GET/POST calls. Instead, another abstraction is taking place that exclusively transfers data from GUI to server and vice versa.<br />
<br />
The Open-Xchange Server includes a session daemon (sessiond) that keeps the current data of a logged in user. If successfully authenticated the information kept in the session are sufficient for accessing the Open-Xchange Server.<br />
<br />
==Access to IMAP Back-End services==<br />
To access external E-Mail systems (IMAP/SMTP) the Open-Xchange Server has to know the credentials of the current user for the system, i. e. the session object has to keep the respective password for the access in plain text. That means authenticating via SessionIDs alone is not sufficient. Authentication always has to take place by entering the username and password.<br />
<br />
(There are two exceptions: either if one master password is used for all IMAP accounts, or if a very special implementation of MAL is used, which does not need a password.)<br />
<br />
==Basic Implementation Rules==<br />
* It must not be possible to get a valid session by e. g. guessing a SessionID. This is especially important when being passed on by an external system<br />
* A session must not be verified by a single SessionID only, but has to compare at least two different data types, this is what the Session-Secret is for<br />
* Both SessionID and Session-Secret must never be passed from the Open-Xchange server to the client in the same request. This ensures, that potential issues in the stack between the client and Open-Xchange (proxies, caches, loadbalancer, Apache, …) can not lead to wrong sessions <br />
* To enhance security Session-Secret and SessionID are transferred as different data types. The Session-Secret will always be transferred as a cookie, the SessionID will be transferred as URL parameter if persistent auto-login is not activated for this session.<br />
* It must never be possible to have conflicting session information per client (multiple cookies) within the same cookie store<br />
* If any error in the session handling is detected, the relevant request is discarded and logged. It is not tried to fix the issue<br />
* In memory data (SessionID) of the browser GUI must never be changed during a valid session<br />
* All relevant information regarding session management must always be written to the relevant logfiles<br />
* The whole mechanism is only secure when being used via encrypted connection<br />
* ATTENTION: If persistent autologin is activated for the system and a user decided to use it, all information necessary to access the Open-Xchange server is stored within the browsers cookie store. This means, that the security of the whole system depends on the level of security of the browsers cookie store<br />
<br />
== Authentication and Session Tokens ==<br />
Following tokens are used for the session management:<br />
<br />
=== SessionID ===<br />
The SessionID is used to identify every session. It is a UUID, generated by the backend via default Java UUID implementation. It is written into the OX logfiles for every log message. When no auto-login is used for the session, then the SessionID is transferred as an URL parameter. If auto-login is activated, then the SessionID is transferred as a cookie.<br />
<br />
=== Session-Secret ===<br />
The Session-Secret is used to verify every session. It is a UUID, generated by the backend via default Java UUID implementation. Only accesses, where the Session-Secret matches with the one stored in SessionD for the given SessionID are valid. Mismatches lead to immediate session termination.<br />
<br />
=== Public Session ===<br />
The public Session is used as a replacement for the SessionID. It is a UUID, generated by the backend via default Java UUID implementation. The Public Session is transferred as a cookie. Using the Public Session is limited to some non critical requests. By using this cookie instead of a request parameter, the browser is able to cache the response of special requests (e.g. contact images).<br />
<br />
=== Random ===<br />
The Random-Token is a one time token with a limited lifetime, which is used to initiate sessions through 3rd party applications or websites. It is a UUID, generated by the backend via default Java UUID implementation. This token is deprecated and subject to change.<br />
<br />
=== Cookie Handling ===<br />
In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply.<br />
<br />
=== Only one cookie per client session type ===<br />
It must never happen, that the same client has more than one session associated with an Open-Xchange server. Therefore the cookies need to have the same name. If a new cookie is set to the browser, the original one will be overwritten. With the next client access either the SessionID or the Session-Secret do not match anymore and the invalid session is terminated.<br />
Multiple clients with same cookie store<br />
<br />
On the other hand it may happen, that several clients use the same cookie store. E.g. a standard browser GUI session and a browser plugin session. Therefore the cookie name needs to contain informations about the client.<br />
<br />
=== Naming of cookies ===<br />
The cookies are named following this schema:<br />
<br />
open-xchange-session-<<name token>>=<<SessionID>><br />
open-xchange-secret-<<name token>>=<<Session-Secret>><br />
<br />
Where <<name token>> is generated from configurable data associated with the client. It is a md5-hash build from the client-id and the User-Agent is used to identify the client. Other parameters can be added through a configuration file. If a request is performed by a browser with an invalid hash the corresponding cookies and session are invalidated.<br />
<br />
===Lifetime of cookies===<br />
Normally, cookies are session cookies, which get invalid/deleted when the browser is shut down. <br />
Using the persistent auto-login, the cookies are persistent cookies, with a configurable default. The default lifetime is one week.<br />
<br />
All cookies get deleted when a logout is performed.<br />
<br />
==IP Check==<br />
Per default an IP check is activated to terminate every session immediately, if the IP address of the client changes during the session lifetime. This check is not processed, when a session is reactivated following the persistent auto-login process.<br />
There are several configuration options to enable, disable the IP Check and to define IP Ranges to omit the check and/or accept recurring connections from within these ranges.<br />
<br />
==Access via web browser with user credentials==<br />
When directly logging in to the system by entering the credentials, following steps will be done to authenticate the user or verify the valid session after the authentication:<br />
<br />
If the user does not use the persistent auto-login, the session is only valid as long as the browser is opened. It will be cleared either on logout, on browser termination or with any occurring error.<br />
<br />
# Browser sends initial request to the Open-Xchange Server<br />
## not authenticated yet<br />
## no cookie<br />
## no SessionID<br />
# Open-Xchange Server sends AJAX application to browser it is loaded, no data is exchanged <br />
# User enters username and password in the front-end<br />
# Username and password are sent to the server via JSON (SSL). If the user activated persistent auto-login on the login screen, this information is passed with the same request<br />
# The server authenticates and sends following data back to the browser via JSON (the data are all saved in the session object in sessiond)<br />
## SessionID in JSON object<br />
## Random token for initial login via JSON object (required for SSO login)<br />
## Cookie with JSESSIONID for loadbalancing is set to the browser<br />
# The second part of the tokens is delivered in a separate request<br />
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity<br />
# AJAX front-end saves the SessionID in memory AJAX front-end ignores random token<br />
# AJAX sends initial data request via JSON to the Open-Xchange Server and provides following data:<br />
## SessionID in JSON object<br />
## Open-Xchange Server processes this data request and requests from browser the cookie with Session-Secret<br />
# Open-Xchange Server compares:<br />
## SessionID for validity in sessiond<br />
## Session-Secret from Cookie for validity with sessiond<br />
# Request is correctly authenticated and is answered<br />
# Random token is discarded after timeout from sessiond <br />
# If persistent auto-login is selected<br />
## Cookie with SessionID is set to the browser The cookie is configured with the relevant type and validity<br />
# Repeat 7. - 10. until end of session<br />
<br />
==Access via web browser after authentication with external system==<br />
The goal is to authenticate in the Open-Xchange system through an external system and to safely pass on the received session data to a browser. To do so the external system has to know the user data (username, password) in plain text. <br />
<br />
The process is based on the session initialization in the Open-Xchange Server via the JSON interface and on passing on the received data to a browser. The browser finally initializes the session with an additional random token that is only valid for one single access. <br />
# External tool sends initial JSON request directly to Open-Xchange Server<br />
## not authenticated yet<br />
## no cookie<br />
## no SessionID<br />
# The Open-Xchange Server authenticates and delivers back following data to external tool via JSON (all the data are stored in the session object in sessiond)<br />
## SessionID in JSON object<br />
## Random token for initial login via JSON object (required for SSO login)<br />
## Cookie with Session-Secret is not set<br />
# External tool starts browser with special URL, that contains at least following data:<br />
## Random token for initial login<br />
# Open-Xchange Server compares:<br />
## Random token for validity in sessiond<br />
# Open-Xchange Server sends to the browser:<br />
## SessionID in JSON object<br />
## Cookie with JSESSIONID for loadbalancing is set to the browser<br />
# The second part of the tokens is delivered in a separate request<br />
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity<br />
# Open-Xchange removes random token from sessiond.<br />
<br />
Then the process continues as described in the section above. The session is then verified with the SessionID and Session-Secret.<br />
<br />
==Token Login==<br />
A dedicated login action (tokenLogin) is used to acquire a server token bound to a given client token. The combination of these tokens allows another client to gain a valid session. This Login is intended to replace the random token login. With this method there is no request or response containing all necessary information to create a valid session.<br />
<br />
==Form Login==<br />
The Form Login provides a simple way of accessing the web frontend just by using standard HTML forms. The response contains a redirect link to the Web-UI. See [[OXSessionFormLogin]] for details.<br />
<br />
==Redeem Token Login==<br />
With a valid session it is possible to acquire a secret. Using this secret another system is able to generate a valid session.<br />
This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.<br />
<br />
== Authentication against other services ==<br />
OX6 and AppSuite allow authentication using other services, too. This is not in the scope of this article. The Services team is available to build plugins for such services. Some standard ones are already implemented, see the following articles for that:<br />
* [[Authentication IMAP Plugin description]] <br />
* [[Authentication LDAP Plugin description]] <br />
<br />
[[Category:Server]]<br />
[[Category:OX6]]<br />
[[Category:AppSuite]]<br />
[[Category:Auth]]</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=Login_variations&diff=17369Login variations2014-04-04T12:34:22Z<p>Dennis Sieben: /* Access via web browser with user credentials */</p>
<hr />
<div><div class="title">Login variations</div><br />
<br />
'''Introduction:''' This paper describes Open-Xchanges's authentication and session handling. It gives an overview of all available mechanisms and on how to safely pass on sessions from external applications to the Open-Xchange Server (Single Sign On, SSO).<br />
<br />
== Overview ==<br />
The Open-Xchange Server web front-end is implemented in AJAX (Asynchronous JavaScript and XML). Thus the complete user interface (GUI) is running in a browser. Opposed to standard web applications there are no HTML pages generated and delivered by the browser.<br />
<br />
The complete user front-end is rendered and displayed in the browser. Based on HTTP/S the data are exchanged with the server via JavaScript Object Notation (JSON). That means it is not possible to simulate front-end actions via HTTP/S request by simulating respectively formatted GET/POST calls. Instead, another abstraction is taking place that exclusively transfers data from GUI to server and vice versa.<br />
<br />
The Open-Xchange Server includes a session daemon (sessiond) that keeps the current data of a logged in user. If successfully authenticated the information kept in the session are sufficient for accessing the Open-Xchange Server.<br />
<br />
==Access to IMAP Back-End services==<br />
To access external E-Mail systems (IMAP/SMTP) the Open-Xchange Server has to know the credentials of the current user for the system, i. e. the session object has to keep the respective password for the access in plain text. That means authenticating via SessionIDs alone is not sufficient. Authentication always has to take place by entering the username and password.<br />
<br />
(There are two exceptions: either if one master password is used for all IMAP accounts, or if a very special implementation of MAL is used, which does not need a password.)<br />
<br />
==Basic Implementation Rules==<br />
* It must not be possible to get a valid session by e. g. guessing a SessionID. This is especially important when being passed on by an external system<br />
* A session must not be verified by a single SessionID only, but has to compare at least two different data types, this is what the Session-Secret is for<br />
* Both SessionID and Session-Secret must never be passed from the Open-Xchange server to the client in the same request. This ensures, that potential issues in the stack between the client and Open-Xchange (proxies, caches, loadbalancer, Apache, …) can not lead to wrong sessions <br />
* To enhance security Session-Secret and SessionID are transferred as different data types. The Session-Secret will always be transferred as a cookie, the SessionID will be transferred as URL parameter if persistent auto-login is not activated for this session.<br />
* It must never be possible to have conflicting session information per client (multiple cookies) within the same cookie store<br />
* If any error in the session handling is detected, the relevant request is discarded and logged. It is not tried to fix the issue<br />
* In memory data (SessionID) of the browser GUI must never be changed during a valid session<br />
* All relevant information regarding session management must always be written to the relevant logfiles<br />
* The whole mechanism is only secure when being used via encrypted connection<br />
* ATTENTION: If persistent autologin is activated for the system and a user decided to use it, all information necessary to access the Open-Xchange server is stored within the browsers cookie store. This means, that the security of the whole system depends on the level of security of the browsers cookie store<br />
<br />
== Authentication and Session Tokens ==<br />
Following tokens are used for the session management:<br />
<br />
=== SessionID ===<br />
The SessionID is used to identify every session. It is a UUID, generated by the backend via default Java UUID implementation. It is written into the OX logfiles for every log message. When no auto-login is used for the session, then the SessionID is transferred as an URL parameter. If auto-login is activated, then the SessionID is transferred as a cookie.<br />
<br />
=== Session-Secret ===<br />
The Session-Secret is used to verify every session. It is a UUID, generated by the backend via default Java UUID implementation. Only accesses, where the Session-Secret matches with the one stored in SessionD for the given SessionID are valid. Mismatches lead to immediate session termination.<br />
<br />
=== Public Session ===<br />
The public Session is used as a replacement for the SessionID. It is a UUID, generated by the backend via default Java UUID implementation. The Public Session is transferred as a cookie. Using the Public Session is limited to some non critical requests. By using this cookie instead of a request parameter, the browser is able to cache the response of special requests (e.g. contact images).<br />
<br />
=== Random ===<br />
The Random-Token is a one time token with a limited lifetime, which is used to initiate sessions through 3rd party applications or websites. It is a UUID, generated by the backend via default Java UUID implementation. This token is deprecated and subject to change.<br />
<br />
=== Cookie Handling ===<br />
In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply.<br />
<br />
=== Only one cookie per client session type ===<br />
It must never happen, that the same client has more than one session associated with an Open-Xchange server. Therefore the cookies need to have the same name. If a new cookie is set to the browser, the original one will be overwritten. With the next client access either the SessionID or the Session-Secret do not match anymore and the invalid session is terminated.<br />
Multiple clients with same cookie store<br />
<br />
On the other hand it may happen, that several clients use the same cookie store. E.g. a standard browser GUI session and a browser plugin session. Therefore the cookie name needs to contain informations about the client.<br />
<br />
=== Naming of cookies ===<br />
The cookies are named following this schema:<br />
<br />
open-xchange-session-<<name token>>=<<SessionID>><br />
open-xchange-secret-<<name token>>=<<Session-Secret>><br />
<br />
Where <<name token>> is generated from configurable data associated with the client. It is a md5-hash build from the client-id and the User-Agent is used to identify the client. Other parameters can be added through a configuration file. If a request is performed by a browser with an invalid hash the corresponding cookies and session are invalidated.<br />
<br />
===Lifetime of cookies===<br />
Normally, cookies are session cookies, which get invalid/deleted when the browser is shut down. <br />
Using the persistent auto-login, the cookies are persistent cookies, with a configurable default. The default lifetime is one week.<br />
<br />
All cookies get deleted when a logout is performed.<br />
<br />
==IP Check==<br />
Per default an IP check is activated to terminate every session immediately, if the IP address of the client changes during the session lifetime. This check is not processed, when a session is reactivated following the persistent auto-login process.<br />
There are several configuration options to enable, disable the IP Check and to define IP Ranges to omit the check and/or accept recurring connections from within these ranges.<br />
<br />
==Access via web browser with user credentials==<br />
When directly logging in to the system by entering the credentials, following steps will be done to authenticate the user or verify the valid session after the authentication:<br />
<br />
If the user does not use the persistent auto-login, the session is only valid as long as the browser is opened. It will be cleared either on logout, on browser termination or with any occurring error.<br />
<br />
# Browser sends initial request to the Open-Xchange Server<br />
## not authenticated yet<br />
## no cookie<br />
## no SessionID<br />
# Open-Xchange Server sends AJAX application to browser it is loaded, no data is exchanged <br />
# User enters username and password in the front-end<br />
# Username and password are sent to the server via JSON (SSL) If the user activated persistent auto-login on the login screen, this information is passed with the same request<br />
# The server authenticates and sends following data back to the browser via JSON (the data are all saved in the session object in sessiond)<br />
## SessionID in JSON object<br />
## Random token for initial login via JSON object (required for SSO login)<br />
## Cookie with JSESSIONID for loadbalancing is set to the browser<br />
# The second part of the tokens is delivered in a separate request<br />
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity<br />
# AJAX front-end saves the SessionID in memory AJAX front-end ignores random token<br />
# AJAX sends initial data request via JSON to the Open-Xchange Server and provides following data:<br />
## SessionID in JSON object<br />
## Open-Xchange Server processes this data request and requests from browser the cookie with Session-Secret<br />
# Open-Xchange Server compares:<br />
## SessionID for validity in sessiond<br />
## Session-Secret from Cookie for validity with sessiond<br />
# Request is correctly authenticated and is answered<br />
# Random token is discarded after timeout from sessiond <br />
# If persistent auto-login is selected<br />
## Cookie with SessionID is set to the browser The cookie is configured with the relevant type and validity<br />
# Repeat 7. - 10. until end of session<br />
<br />
==Access via web browser after authentication with external system==<br />
The goal is to authenticate in the Open-Xchange system through an external system and to safely pass on the received session data to a browser. To do so the external system has to know the user data (username, password) in plain text. <br />
<br />
The process is based on the session initialization in the Open-Xchange Server via the JSON interface and on passing on the received data to a browser. The browser finally initializes the session with an additional random token that is only valid for one single access. <br />
# External tool sends initial JSON request directly to Open-Xchange Server<br />
## not authenticated yet<br />
## no cookie<br />
## no SessionID<br />
# The Open-Xchange Server authenticates and delivers back following data to external tool via JSON (all the data are stored in the session object in sessiond)<br />
## SessionID in JSON object<br />
## Random token for initial login via JSON object (required for SSO login)<br />
## Cookie with Session-Secret is not set<br />
# External tool starts browser with special URL, that contains at least following data:<br />
## Random token for initial login<br />
# Open-Xchange Server compares:<br />
## Random token for validity in sessiond<br />
# Open-Xchange Server sends to the browser:<br />
## SessionID in JSON object<br />
## Cookie with JSESSIONID for loadbalancing is set to the browser<br />
# The second part of the tokens is delivered in a separate request<br />
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity<br />
# Open-Xchange removes random token from sessiond.<br />
<br />
Then the process continues as described in the section above. The session is then verified with the SessionID and Session-Secret.<br />
<br />
==Token Login==<br />
A dedicated login action (tokenLogin) is used to acquire a server token bound to a given client token. The combination of these tokens allows another client to gain a valid session. This Login is intended to replace the random token login. With this method there is no request or response containing all necessary information to create a valid session.<br />
<br />
==Form Login==<br />
The Form Login provides a simple way of accessing the web frontend just by using standard HTML forms. The response contains a redirect link to the Web-UI. See [[OXSessionFormLogin]] for details.<br />
<br />
==Redeem Token Login==<br />
With a valid session it is possible to acquire a secret. Using this secret another system is able to generate a valid session.<br />
This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.<br />
<br />
== Authentication against other services ==<br />
OX6 and AppSuite allow authentication using other services, too. This is not in the scope of this article. The Services team is available to build plugins for such services. Some standard ones are already implemented, see the following articles for that:<br />
* [[Authentication IMAP Plugin description]] <br />
* [[Authentication LDAP Plugin description]] <br />
<br />
[[Category:Server]]<br />
[[Category:OX6]]<br />
[[Category:AppSuite]]<br />
[[Category:Auth]]</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=Login_variations&diff=17368Login variations2014-04-04T12:33:48Z<p>Dennis Sieben: /* Access via web browser with user credentials */</p>
<hr />
<div><div class="title">Login variations</div><br />
<br />
'''Introduction:''' This paper describes Open-Xchanges's authentication and session handling. It gives an overview of all available mechanisms and on how to safely pass on sessions from external applications to the Open-Xchange Server (Single Sign On, SSO).<br />
<br />
== Overview ==<br />
The Open-Xchange Server web front-end is implemented in AJAX (Asynchronous JavaScript and XML). Thus the complete user interface (GUI) is running in a browser. Opposed to standard web applications there are no HTML pages generated and delivered by the browser.<br />
<br />
The complete user front-end is rendered and displayed in the browser. Based on HTTP/S the data are exchanged with the server via JavaScript Object Notation (JSON). That means it is not possible to simulate front-end actions via HTTP/S request by simulating respectively formatted GET/POST calls. Instead, another abstraction is taking place that exclusively transfers data from GUI to server and vice versa.<br />
<br />
The Open-Xchange Server includes a session daemon (sessiond) that keeps the current data of a logged in user. If successfully authenticated the information kept in the session are sufficient for accessing the Open-Xchange Server.<br />
<br />
==Access to IMAP Back-End services==<br />
To access external E-Mail systems (IMAP/SMTP) the Open-Xchange Server has to know the credentials of the current user for the system, i. e. the session object has to keep the respective password for the access in plain text. That means authenticating via SessionIDs alone is not sufficient. Authentication always has to take place by entering the username and password.<br />
<br />
(There are two exceptions: either if one master password is used for all IMAP accounts, or if a very special implementation of MAL is used, which does not need a password.)<br />
<br />
==Basic Implementation Rules==<br />
* It must not be possible to get a valid session by e. g. guessing a SessionID. This is especially important when being passed on by an external system<br />
* A session must not be verified by a single SessionID only, but has to compare at least two different data types, this is what the Session-Secret is for<br />
* Both SessionID and Session-Secret must never be passed from the Open-Xchange server to the client in the same request. This ensures, that potential issues in the stack between the client and Open-Xchange (proxies, caches, loadbalancer, Apache, …) can not lead to wrong sessions <br />
* To enhance security Session-Secret and SessionID are transferred as different data types. The Session-Secret will always be transferred as a cookie, the SessionID will be transferred as URL parameter if persistent auto-login is not activated for this session.<br />
* It must never be possible to have conflicting session information per client (multiple cookies) within the same cookie store<br />
* If any error in the session handling is detected, the relevant request is discarded and logged. It is not tried to fix the issue<br />
* In memory data (SessionID) of the browser GUI must never be changed during a valid session<br />
* All relevant information regarding session management must always be written to the relevant logfiles<br />
* The whole mechanism is only secure when being used via encrypted connection<br />
* ATTENTION: If persistent autologin is activated for the system and a user decided to use it, all information necessary to access the Open-Xchange server is stored within the browsers cookie store. This means, that the security of the whole system depends on the level of security of the browsers cookie store<br />
<br />
== Authentication and Session Tokens ==<br />
Following tokens are used for the session management:<br />
<br />
=== SessionID ===<br />
The SessionID is used to identify every session. It is a UUID, generated by the backend via default Java UUID implementation. It is written into the OX logfiles for every log message. When no auto-login is used for the session, then the SessionID is transferred as an URL parameter. If auto-login is activated, then the SessionID is transferred as a cookie.<br />
<br />
=== Session-Secret ===<br />
The Session-Secret is used to verify every session. It is a UUID, generated by the backend via default Java UUID implementation. Only accesses, where the Session-Secret matches with the one stored in SessionD for the given SessionID are valid. Mismatches lead to immediate session termination.<br />
<br />
=== Public Session ===<br />
The public Session is used as a replacement for the SessionID. It is a UUID, generated by the backend via default Java UUID implementation. The Public Session is transferred as a cookie. Using the Public Session is limited to some non critical requests. By using this cookie instead of a request parameter, the browser is able to cache the response of special requests (e.g. contact images).<br />
<br />
=== Random ===<br />
The Random-Token is a one time token with a limited lifetime, which is used to initiate sessions through 3rd party applications or websites. It is a UUID, generated by the backend via default Java UUID implementation. This token is deprecated and subject to change.<br />
<br />
=== Cookie Handling ===<br />
In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply.<br />
<br />
=== Only one cookie per client session type ===<br />
It must never happen, that the same client has more than one session associated with an Open-Xchange server. Therefore the cookies need to have the same name. If a new cookie is set to the browser, the original one will be overwritten. With the next client access either the SessionID or the Session-Secret do not match anymore and the invalid session is terminated.<br />
Multiple clients with same cookie store<br />
<br />
On the other hand it may happen, that several clients use the same cookie store. E.g. a standard browser GUI session and a browser plugin session. Therefore the cookie name needs to contain informations about the client.<br />
<br />
=== Naming of cookies ===<br />
The cookies are named following this schema:<br />
<br />
open-xchange-session-<<name token>>=<<SessionID>><br />
open-xchange-secret-<<name token>>=<<Session-Secret>><br />
<br />
Where <<name token>> is generated from configurable data associated with the client. It is a md5-hash build from the client-id and the User-Agent is used to identify the client. Other parameters can be added through a configuration file. If a request is performed by a browser with an invalid hash the corresponding cookies and session are invalidated.<br />
<br />
===Lifetime of cookies===<br />
Normally, cookies are session cookies, which get invalid/deleted when the browser is shut down. <br />
Using the persistent auto-login, the cookies are persistent cookies, with a configurable default. The default lifetime is one week.<br />
<br />
All cookies get deleted when a logout is performed.<br />
<br />
==IP Check==<br />
Per default an IP check is activated to terminate every session immediately, if the IP address of the client changes during the session lifetime. This check is not processed, when a session is reactivated following the persistent auto-login process.<br />
There are several configuration options to enable, disable the IP Check and to define IP Ranges to omit the check and/or accept recurring connections from within these ranges.<br />
<br />
==Access via web browser with user credentials==<br />
When directly logging in to the system by entering the credentials, following steps will be done to authenticate the user or verify the valid session after the authentication:<br />
<br />
If the user does not use the persistent auto-login, the session is only valid as long, as the browser is opened. It will be cleared either on logout, on browser termination or with any occurring error.<br />
<br />
# Browser sends initial request to the Open-Xchange Server<br />
## not authenticated yet<br />
## no cookie<br />
## no SessionID<br />
# Open-Xchange Server sends AJAX application to browser it is loaded, no data is exchanged <br />
# User enters username and password in the front-end<br />
# Username and password are sent to the server via JSON (SSL) If the user activated persistent auto-login on the login screen, this information is passed with the same request<br />
# The server authenticates and sends following data back to the browser via JSON (the data are all saved in the session object in sessiond)<br />
## SessionID in JSON object<br />
## Random token for initial login via JSON object (required for SSO login)<br />
## Cookie with JSESSIONID for loadbalancing is set to the browser<br />
# The second part of the tokens is delivered in a separate request<br />
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity<br />
# AJAX front-end saves the SessionID in memory AJAX front-end ignores random token<br />
# AJAX sends initial data request via JSON to the Open-Xchange Server and provides following data:<br />
## SessionID in JSON object<br />
## Open-Xchange Server processes this data request and requests from browser the cookie with Session-Secret<br />
# Open-Xchange Server compares:<br />
## SessionID for validity in sessiond<br />
## Session-Secret from Cookie for validity with sessiond<br />
# Request is correctly authenticated and is answered<br />
# Random token is discarded after timeout from sessiond <br />
# If persistent auto-login is selected<br />
## Cookie with SessionID is set to the browser The cookie is configured with the relevant type and validity<br />
# Repeat 7. - 10. until end of session<br />
<br />
==Access via web browser after authentication with external system==<br />
The goal is to authenticate in the Open-Xchange system through an external system and to safely pass on the received session data to a browser. To do so the external system has to know the user data (username, password) in plain text. <br />
<br />
The process is based on the session initialization in the Open-Xchange Server via the JSON interface and on passing on the received data to a browser. The browser finally initializes the session with an additional random token that is only valid for one single access. <br />
# External tool sends initial JSON request directly to Open-Xchange Server<br />
## not authenticated yet<br />
## no cookie<br />
## no SessionID<br />
# The Open-Xchange Server authenticates and delivers back following data to external tool via JSON (all the data are stored in the session object in sessiond)<br />
## SessionID in JSON object<br />
## Random token for initial login via JSON object (required for SSO login)<br />
## Cookie with Session-Secret is not set<br />
# External tool starts browser with special URL, that contains at least following data:<br />
## Random token for initial login<br />
# Open-Xchange Server compares:<br />
## Random token for validity in sessiond<br />
# Open-Xchange Server sends to the browser:<br />
## SessionID in JSON object<br />
## Cookie with JSESSIONID for loadbalancing is set to the browser<br />
# The second part of the tokens is delivered in a separate request<br />
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity<br />
# Open-Xchange removes random token from sessiond.<br />
<br />
Then the process continues as described in the section above. The session is then verified with the SessionID and Session-Secret.<br />
<br />
==Token Login==<br />
A dedicated login action (tokenLogin) is used to acquire a server token bound to a given client token. The combination of these tokens allows another client to gain a valid session. This Login is intended to replace the random token login. With this method there is no request or response containing all necessary information to create a valid session.<br />
<br />
==Form Login==<br />
The Form Login provides a simple way of accessing the web frontend just by using standard HTML forms. The response contains a redirect link to the Web-UI. See [[OXSessionFormLogin]] for details.<br />
<br />
==Redeem Token Login==<br />
With a valid session it is possible to acquire a secret. Using this secret another system is able to generate a valid session.<br />
This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.<br />
<br />
== Authentication against other services ==<br />
OX6 and AppSuite allow authentication using other services, too. This is not in the scope of this article. The Services team is available to build plugins for such services. Some standard ones are already implemented, see the following articles for that:<br />
* [[Authentication IMAP Plugin description]] <br />
* [[Authentication LDAP Plugin description]] <br />
<br />
[[Category:Server]]<br />
[[Category:OX6]]<br />
[[Category:AppSuite]]<br />
[[Category:Auth]]</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=HTTP_API_MailFilter&diff=16970HTTP API MailFilter2014-02-03T16:36:06Z<p>Dennis Sieben: /* Get the configuration of the mail filter backend */</p>
<hr />
<div><center>'''Open-Xchange Mail Filter HTTP API'''</center><br />
<br />
= Introduction =<br />
This document describes only the mail filter HTTP-API. So it's only a part which must be embedded into something which counts for login/logout, session handling and low-level protocol issues such as error handling. At the moment this will be the groupware server. So the modules needed for basic operations can be found there.<br />
<br />
= Module mailfilter =<br />
This module is used to access all mail filter related options.<br />
<br />
First of all the main structure of a mail filter script is, that it has different rules. Each of them contains one command. This command takes a test condition which executes the actions given in that command if the test condition is true.<br />
<br />
The test condition consists of a test command and some arguments for this command depending on the command itself. Because the available tests depend on the mail filter server, these tests must be determined at runtime. So that no test field is transferred to the server which it isn't able to handle. Examples for tests are <tt>address</tt>, <tt>allof</tt> and <tt>anyof</tt>.<br />
<br />
Each test has a special comparison. The list of available comparisons depends on the test given and the mail filter server configuration so they have to be determined at runtime too.<br />
<br />
Each time you want to do some action on a mail you need a so called action command. This describes what to do with a mail. To action commands the same applies as to the test commands and their comparison types, they must be determined at runtime.<br />
<br />
All those dynamical values can be fetched via a config object at startup. This object shows the capabilities of the server to the client. This allows the client to show only the capabilities the server actually has to the user and to send only objects to the server which produce no errors on the server side.<br />
<br />
To deal with this high flexibility of mail filters this specification can be roughly divided into 2 parts. A non-changing core and dynamical extensions. The core specification is that each rule consists of a name, an ID, a value showing if this rule is active or not and a tag which can be set on a rule to mark that rule for a special purpose. Furthermore each rule takes a test object, specifying in what case the following actions are triggered, and one or many actioncommands, specifying the actions itself. For a detailed specification see [[#Table 1|Table 1]].<br />
<br />
The objects for the tests and the actions are dynamical, so the set presented in this specification may be changed over the time, but only compatible changes are allowed to the objects, otherwise new test or action objects have to be introduced. Due to the fact that not every sieve implementation will offer all the capabilities written in this document, the server will sent his configuration if a special request is made. This configuration will show which of the tests and which of the actions are allowed. So for example if the server signals that it is capable of handling vacation, sending a vacation object as action is safe.<br />
<br />
Furthermore some tests use a comparison field as stated above which specifies how the fields are compared. The values of this field must also be determined at runtime. So in the configuration object there is a special part which shows the comparisons which are available. Note that not all comparisons can be used with every test. Some of them are denoted to a special test, which can be found in the [[#Table 3|Table 3]].<br />
<br />
= The core =<br />
As written in the introduction the main part of a mail filter are the rules. A rule object will always have the structure you can see in the table below ([[#Table 1|Table 1]]). The dynamical parts are the test, which are represented by different options, see [[#Tests|4.1. Tests]], and the actions, also represented in [[#Actions|4.2. Actions]]. Note that the test and actioncmds fields and the text and errormsg fields are mutual exclusive. So if test and actioncmds fields are filled the text and errormsg fields are not present and vice versa.<br />
<br />
{| id="Table 1" cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| Integer<br />
| <br />
| A unique identifier (once created must not be changed)<br />
<br />
|-<br />
| position<br />
| Integer<br />
| <br />
| The position inside the mail filter list. Starts with 0<br />
<br />
|-<br />
| rulename<br />
| String<br />
| <br />
| A name describing the rule, can be empty but must not contain a line break<br />
<br />
|-<br />
| active<br />
| Boolean<br />
| <br />
| If this rule is active or not<br />
<br />
|-<br />
| flags<br />
| Array<br />
| <br />
| A string array containing flags which are set on this rule. Each flag can only contain the following characters: 1-9 a-z A-Z. Currently 2 flags are reserved here: "spam" which marks the default spam rule and "vacation" which marks the vacation rules.<br />
<br />
|-<br />
| test<br />
| Object<br />
| <br />
| The structure of the different test objects can be found in section [[#Tests|4.1. Tests]]. The valid tests in the current setup can be found in the configuration object <br />
<br />
|-<br />
| actioncmds<br />
| Array<br />
| <br />
| An array of action objects whose different structures can be found in section [[#Actions|4.2. Actions]]. The action commands which are valid here can be determined through the config object see Table 24<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| If this rule cannot be read in this string is filled containing the whole lines of this command.<br />
<br />
|-<br />
| errormsg<br />
| String<br />
| <br />
| If this rule cannot be read in this string is filled containing a message why, or what part of the rule isn't known<br />
<br />
|}<br />
<center>''Table 1: Structure of a rule''</center><br />
<br />
= The dynamical part =<br />
== Tests ==<br />
In this section you will find the structures of all test commands which are specified until now. First a complete list of all test commands is given with a short description of them, afterwards a complete list of all comparison as they belong to the test section. Finally the different objects for those test commands are specified.<br />
<br />
<br />
{| id="Table 2" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| address<br />
| This test type applies to addresses only. So it may be used for all header fields which contain addresses. This test returns true if any combination of the header-list and values-list arguments match.<br />
<br />
|-<br />
| envelope<br />
| This test applies to the envelope of a mail. This test isn't used under normal circumstances as the envelope isn't accessible in all mail setups. This test returns true if any combination of the header-list and values-list arguments match'''.'''<br />
<br />
|-<br />
| true<br />
| A test for a true result (can be used if an action command should be executed every time)'''.'''<br />
<br />
|-<br />
| not<br />
| Negates a given test'''.'''<br />
<br />
|-<br />
| size<br />
| Deals with the size of the mail'''.'''<br />
<br />
|-<br />
| currentdate<br />
| Compares a given date with the current date ('''available with 6.20''')<br />
<br />
|-<br />
| header<br />
| Tests against all headers of a mail. So with this test in contrast to the address test also fields such as subject can be handled. This test returns true if any combination of the header-list and values-list arguments match.<br />
<br />
|-<br />
| body<br />
| Tests against the content of a mail.<br />
<br />
|-<br />
| allof<br />
| Defines an AND condition between several tests'''.'''<br />
<br />
|-<br />
| anyof<br />
| Defines an OR condition between several tests'''.'''<br />
<br />
|}<br />
<center>''Table 2: List of all possible tests''</center><br />
<br />
<br />
{| id="Table 3" cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| is<br />
| If a field is equal to a given value<br />
<br />
|-<br />
| contains<br />
| If a field contains a given value at any position<br />
<br />
|-<br />
| matches<br />
| Tests if the value matches the value in the specified field. Here some wild cards can be used. "*" matches zero or more characters, and "?" matches a single character. To use the characters themselves they have to be escaped via a backslash.<br />
<br />
|-<br />
| regex<br />
| Tests if a given regular expression matches with the value present in the specified field.<br />
<br />
|-<br />
| user<br />
| Tests if the user part of an e-mail address is the value given here. This means in [mailto:herbert+mustermann@example.com herbert+mustermann@example.com]. The user checks the part herbert.<br />
<br />
'''Attention: '''This comparison can only be used in conjunction with the address test<br />
<br />
|-<br />
| detail<br />
| Tests if the detail part of an e-mail address is the value given here. In the example above this evaluates to mustermann.<br />
<br />
'''Attention: '''This comparison can only be used in conjunction with the address test<br />
<br />
|}<br />
<center>''Table 3: List of all possible comparisons''</center><br />
<br />
<br />
<br />
{| id="Table 4" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| address<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see [[#Table 26|Table 26]]).<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields. The test will be true if any of the strings matches<br />
<br />
|}<br />
<center>''Table 4: Structure of address-test''</center><br />
<br />
<br />
{| id="Table 5" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| envelope<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see [[#Table 26|Table 26]]).<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields. The test will be true if any of the strings matches<br />
<br />
|}<br />
<center>''Table 5: Structure of envelope-test''</center><br />
<br />
<br />
{| id="Table 6" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| true<br />
| A string describing the test command.<br />
<br />
|}<br />
<center>''Table 6: Structure of true-test''</center><br />
<br />
<br />
{| id="Table 7" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| not<br />
| A string describing the test command.<br />
<br />
|-<br />
| test<br />
| Object<br />
| <br />
| One of the test objects which result will be negated<br />
<br />
|}<br />
<center>''Table 7: Structure of not-test''</center><br />
<br />
<br />
{| id="Table 8" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| size<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Only two types are valid here. A description can be found in [[#Table 9|Table 9]].<br />
<br />
|-<br />
| size<br />
| Number<br />
| <br />
| A number specifying the size for this comparison, in bytes.<br />
<br />
|}<br />
<center>''Table 8: Structure of size-test''</center><br />
<br />
<br />
{| id="Table 9" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| over<br />
| Used in the size test to check for a value greater than the given one<br />
<br />
|-<br />
| under<br />
| Used in the size test to check for a value less than the given one<br />
<br />
|}<br />
<center>''Table 9: Types of comparison for size''</center><br />
<br />
<br />
<br />
{| id="currentdate" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| currentdate<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Only three types are valid here. A description can be found in [[#Table 11|Table 11]].<br />
<br />
|-<br />
| datepart<br />
| String<br />
| <br />
| A string containing the string "date" as we only allow fix date comparisions for now.<br />
<br />
|-<br />
| datevalue<br />
| Array<br />
| <br />
| A value array containing the corresponding value to the datepart. For "date" this will be an array of "Date". The test will be true if any of the values matches<br />
<br />
|}<br />
<center>''Table 10: Structure of currentdate-test''</center><br />
<br />
<br />
<br />
{| id="Table 11" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| is<br />
| Used in the date test to check for a value equal to the given one<br />
<br />
|-<br />
| ge<br />
| Used in the date test to check for a value greater or equal to the given one<br />
<br />
|-<br />
| le<br />
| Used in the date test to check for a value less or equal to the given one<br />
<br />
|}<br />
<center>''Table 11: Types of comparison for currentdate''</center><br />
<br />
<br />
<br />
{| id="Table 12" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| header<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see [[#Table 26|Table 26]])<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the values for the header fields. The test will be true if any of the strings matches<br />
<br />
|}<br />
<center>''Table 12: Structure of header-test''</center><br />
<br />
<br />
{| id="Table 13" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| body<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see [[#Table 26|Table 26]]).<br />
<br />
|-<br />
| extensionskey<br />
| String<br />
| <br />
| The extension key can be one of the value found in [[#Table 12|Table 12]]<br />
<br />
|-<br />
| extensionsvalue<br />
| String<br />
| <br />
| A value for the given key. If the key has no value (see [[#Table 12|Table 12]] for this information) the value given here is ignored<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the values for the body. The test will be true if any of the strings matches<br />
<br />
|}<br />
<center>''Table 13: Structure of body-test''</center><br />
<br />
<br />
{| id="Table 14" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| content<br />
| An extension used in conjunction with the body test to define the content which should be considered. This extension will need a parameter specifying the mime-type of the part of the message which will be searched.<br />
<br />
|-<br />
| text<br />
| An extension used in conjunction with the body test to define that only the text of the body should be considered in this test. This extension takes no parameter<br />
<br />
|}<br />
<center>''Table 14: List of possible extensions''</center><br />
<br />
<br />
{| id="Table 15" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| allof<br />
| A string describing the test command.<br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| A array of tests<br />
<br />
|}<br />
<center>''Table 15: Structure of allof-test''</center><br />
<br />
<br />
{| id="Table 16" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| anyof<br />
| A string describing the test command.<br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| A array of tests<br />
<br />
|}<br />
<center>''Table 16: Structure of anyof-test''</center><br />
<br />
== Actions ==<br />
In this section you will find the structures of all action commands which are specified until now. First a complete list of all action commands is given with a short description of them, later on the different objects for those commands are specified.<br />
<br />
<br />
{| id="Table 17" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| keep<br />
| Keeps a mail non changed<br />
<br />
|-<br />
| discard<br />
| Discards a mail without any processing<br />
<br />
|-<br />
| redirect<br />
| Redirects a mail to a given e-mail address<br />
<br />
|-<br />
| move<br />
| Moves a mail into a given subfolder. The syntax for the subfolder given here. Must be the correct syntax of the underlying IMAP-server. So it is up to the GUI to detect things such as altnamespace or unixhierarchysep.<br />
<br />
|-<br />
| reject<br />
| Rejects the mail with a given text<br />
<br />
|-<br />
| stop<br />
| Stops any further progressing of a mail<br />
<br />
|-<br />
| vacation<br />
| Creates a vacation mail<br />
<br />
|-<br />
| addflags<br />
| Adds flags to a mail<br />
<br />
|-<br />
| notify<br />
| adds a notification<br />
<br />
|-<br />
| pgp<br />
| encrypts a mail via pgp<br />
<br />
|}<br />
<center>''Table 17: List of possible action commands''</center><br />
<br />
<br />
{| id="Table 18" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| keep<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 18: Structure of keep-command''</center><br />
<br />
<br />
{| id="Table 19" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| discard<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 19: Structure of discard-command''</center><br />
<br />
<br />
{| id="Table 20" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| redirect<br />
| A string defining the object itself<br />
<br />
|-<br />
| to<br />
| String<br />
| <br />
| A string containing where the mail should be redirected to<br />
<br />
|}<br />
<center>''Table 20: Structure of redirect-command''</center><br />
<br />
<br />
{| id="Table 21" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| move<br />
| A string defining the object itself<br />
<br />
|-<br />
| into<br />
| String<br />
| <br />
| This string takes the object id of the destination mail folder as specified in the HTTP API of the groupware<br />
<br />
|}<br />
<center>''Table 21: Structure of move-command''</center><br />
<br />
<br />
{| id="Table 22" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| reject<br />
| A string defining the object itself<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| A string containing the reason why the mail is rejected<br />
<br />
|}<br />
<center>''Table 22: Structure of reject-command''</center><br />
<br />
<br />
{| id="Table 23" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| stop<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 23: Structure of stop-command''</center><br />
<br />
<br />
{| id="Table 24" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| vacation<br />
| A string defining the object itself<br />
<br />
|-<br />
| days<br />
| Integer<br />
| <br />
| The days for which a vacation text is returned<br />
<br />
|-<br />
| addresses<br />
| Array<br />
| <br />
| The addresses for which this vacation is responsible. That means for which addresses out of the aliases array of the user defining this filter, vacations will be sent.<br />
<br />
|-<br />
| subject<br />
| String<br />
| <br />
| The new subject for the returned message (can be left empty, when only adding RE:)<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| The vacation text itself<br />
<br />
|}<br />
<center>''Table 24: Structure of vacation-command''</center><br />
<br />
<br />
{| id="Table 25" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| addflags<br />
| A string defining the object itself<br />
<br />
|-<br />
| flags<br />
| Array<br />
| <br />
| An array containing the flags which should be added to that mail. A flag can be either a system flag or a user flag. System flags begin with a backslash (\) and can be one of the following:<br />
* \seen<br />
* \answered<br />
* \flagged<br />
* \deleted<br />
* \draft<br />
* \recent<br />
System flags are case-insensitive.<br />
<br />
User flags begin with a dollar sign ($) and can contain any ASCII characters between 0x21 (!) and 0x7E (~), inclusive, except for the characters 0x22, 0x25, 0x28, 0x29, 0x2A, 0x5C, 0x5D and 0x7B, which correspond to<br />
"%()*\]{<br />
Mail color flags as used by OX are implemented by user flags of the form $cl_''n'', where ''n'' is a number between 1 and 10, includive.<br />
<br />
See RFC 3501 for further details on IMAP flags and their meanings.<br />
|}<br />
<center>''Table 25: Structure of addflags-command''</center><br />
<br />
{| id="Table 26" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| notify<br />
| A string defining the object itself<br />
<br />
|-<br />
| message<br />
| String<br />
| <br />
| the content of the notification message<br />
<br />
|-<br />
| method<br />
| String<br />
| <br />
| the method of the notification message, e.g. <pre>"mailto:012345678@sms.gateway"</pre><br />
<br />
|}<br />
<center>''Table 26: Structure of notify-command''</center><br />
<br />
{| id="Table 27" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| pgp<br />
| A string defining the object itself<br />
<br />
|-<br />
| keys<br />
| Array<br />
| <br />
| The public keys as string which should be used for encryption<br />
<br />
|}<br />
<center>''Table 27: Structure of pgp-command''</center><br />
<br />
= Requests =<br />
== Get the configuration of the mail filter backend ==<br />
<tt>GET /ajax/mailfilter?action=config</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Response body: An object describing the configuration like described in [[#Table 28|Table 28]].<br />
<br />
<br />
{| id="Table 28" cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| An array containing test-objects like described in [[#Table 29|Table 29]]<br />
<br />
|-<br />
| actioncommands<br />
| Array<br />
| <br />
| An array containing the valid action commands as strings. A list of all possible values can be found in [[#Table 17|Table 17]].<br />
<br />
|}<br />
<center>''Table 28: Config object''</center><br />
<br />
<br />
{| id="Table 29" cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| test<br />
| String<br />
| <br />
| A name for the test. A list of all possible tests can be found in [[#Table 2|Table 2]]. The corresponding objects can be used in the test field in [[#Table 1|Table 1]].<br />
<br />
|-<br />
| comparison<br />
| Array<br />
| <br />
| A string array containing the valid comparison types for this test. Possible values are given in [[#Table 3|Table 3]]. Values given in this array can be used in the comparison field in <br />
<br />
|}<br />
<center>''Table 29: Test object''</center><br />
<br />
== Get all mail filter rules ==<br />
<tt>GET /ajax/mailfilter?action=list</tt><br />
<br />
Parameters:<br />
<br />
* <tt>flag</tt> If given, only rules with this flag are returned<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Response body: An array of rule objects like described in [[#Table 1|Table 1]].<br />
<br />
== Create a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=new</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Request body: Rule object as described in [[#Table 1|Table 1]]. If the field <tt>position</tt> is included in [[#Table 1|Table 1]] it's taken as the position of the rule in the array on the server side. Note that this value shouldn't be greater than the size of all rules<br />
<br />
Response body: An integer for the id of the new created rule.<br />
<br />
== Delete a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=delete</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Request body: An object with the field <tt>id</tt>.<br />
<br />
== Reorder mail filter rules ==<br />
PUT <tt>/ajax/mailfilter?action=reorder</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Request body: An array of unique ids which represents how the rule with the corresponding unique ids are ordered<br />
<br />
== Update a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=update</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Request body: Rule object as described in [[#Table 1|Table 1]] with the <tt>id</tt> set (which identifies the rule to change). Only modified fields are present.<br />
<br />
== Delete the whole script ==<br />
PUT <tt>/ajax/mailfilter?action=deletescript</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Note that this call is only used as workaround for parsing errors in the backend, so that the user is able to kick a whole script if it contains errors in the grammar.<br />
<br />
== Get the whole script ==<br />
PUT <tt>/ajax/mailfilter?action=getscript</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Response body: A text of the complete sieve script<br />
<br />
Note that this call is only used as workaround for parsing errors in the backend, so that the user is able to get the plaintext of a complete script.</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=HTTP_API_MailFilter&diff=16969HTTP API MailFilter2014-02-03T16:35:15Z<p>Dennis Sieben: /* Get the configuration of the mail filter backend */</p>
<hr />
<div><center>'''Open-Xchange Mail Filter HTTP API'''</center><br />
<br />
= Introduction =<br />
This document describes only the mail filter HTTP-API. So it's only a part which must be embedded into something which counts for login/logout, session handling and low-level protocol issues such as error handling. At the moment this will be the groupware server. So the modules needed for basic operations can be found there.<br />
<br />
= Module mailfilter =<br />
This module is used to access all mail filter related options.<br />
<br />
First of all the main structure of a mail filter script is, that it has different rules. Each of them contains one command. This command takes a test condition which executes the actions given in that command if the test condition is true.<br />
<br />
The test condition consists of a test command and some arguments for this command depending on the command itself. Because the available tests depend on the mail filter server, these tests must be determined at runtime. So that no test field is transferred to the server which it isn't able to handle. Examples for tests are <tt>address</tt>, <tt>allof</tt> and <tt>anyof</tt>.<br />
<br />
Each test has a special comparison. The list of available comparisons depends on the test given and the mail filter server configuration so they have to be determined at runtime too.<br />
<br />
Each time you want to do some action on a mail you need a so called action command. This describes what to do with a mail. To action commands the same applies as to the test commands and their comparison types, they must be determined at runtime.<br />
<br />
All those dynamical values can be fetched via a config object at startup. This object shows the capabilities of the server to the client. This allows the client to show only the capabilities the server actually has to the user and to send only objects to the server which produce no errors on the server side.<br />
<br />
To deal with this high flexibility of mail filters this specification can be roughly divided into 2 parts. A non-changing core and dynamical extensions. The core specification is that each rule consists of a name, an ID, a value showing if this rule is active or not and a tag which can be set on a rule to mark that rule for a special purpose. Furthermore each rule takes a test object, specifying in what case the following actions are triggered, and one or many actioncommands, specifying the actions itself. For a detailed specification see [[#Table 1|Table 1]].<br />
<br />
The objects for the tests and the actions are dynamical, so the set presented in this specification may be changed over the time, but only compatible changes are allowed to the objects, otherwise new test or action objects have to be introduced. Due to the fact that not every sieve implementation will offer all the capabilities written in this document, the server will sent his configuration if a special request is made. This configuration will show which of the tests and which of the actions are allowed. So for example if the server signals that it is capable of handling vacation, sending a vacation object as action is safe.<br />
<br />
Furthermore some tests use a comparison field as stated above which specifies how the fields are compared. The values of this field must also be determined at runtime. So in the configuration object there is a special part which shows the comparisons which are available. Note that not all comparisons can be used with every test. Some of them are denoted to a special test, which can be found in the [[#Table 3|Table 3]].<br />
<br />
= The core =<br />
As written in the introduction the main part of a mail filter are the rules. A rule object will always have the structure you can see in the table below ([[#Table 1|Table 1]]). The dynamical parts are the test, which are represented by different options, see [[#Tests|4.1. Tests]], and the actions, also represented in [[#Actions|4.2. Actions]]. Note that the test and actioncmds fields and the text and errormsg fields are mutual exclusive. So if test and actioncmds fields are filled the text and errormsg fields are not present and vice versa.<br />
<br />
{| id="Table 1" cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| Integer<br />
| <br />
| A unique identifier (once created must not be changed)<br />
<br />
|-<br />
| position<br />
| Integer<br />
| <br />
| The position inside the mail filter list. Starts with 0<br />
<br />
|-<br />
| rulename<br />
| String<br />
| <br />
| A name describing the rule, can be empty but must not contain a line break<br />
<br />
|-<br />
| active<br />
| Boolean<br />
| <br />
| If this rule is active or not<br />
<br />
|-<br />
| flags<br />
| Array<br />
| <br />
| A string array containing flags which are set on this rule. Each flag can only contain the following characters: 1-9 a-z A-Z. Currently 2 flags are reserved here: "spam" which marks the default spam rule and "vacation" which marks the vacation rules.<br />
<br />
|-<br />
| test<br />
| Object<br />
| <br />
| The structure of the different test objects can be found in section [[#Tests|4.1. Tests]]. The valid tests in the current setup can be found in the configuration object <br />
<br />
|-<br />
| actioncmds<br />
| Array<br />
| <br />
| An array of action objects whose different structures can be found in section [[#Actions|4.2. Actions]]. The action commands which are valid here can be determined through the config object see Table 24<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| If this rule cannot be read in this string is filled containing the whole lines of this command.<br />
<br />
|-<br />
| errormsg<br />
| String<br />
| <br />
| If this rule cannot be read in this string is filled containing a message why, or what part of the rule isn't known<br />
<br />
|}<br />
<center>''Table 1: Structure of a rule''</center><br />
<br />
= The dynamical part =<br />
== Tests ==<br />
In this section you will find the structures of all test commands which are specified until now. First a complete list of all test commands is given with a short description of them, afterwards a complete list of all comparison as they belong to the test section. Finally the different objects for those test commands are specified.<br />
<br />
<br />
{| id="Table 2" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| address<br />
| This test type applies to addresses only. So it may be used for all header fields which contain addresses. This test returns true if any combination of the header-list and values-list arguments match.<br />
<br />
|-<br />
| envelope<br />
| This test applies to the envelope of a mail. This test isn't used under normal circumstances as the envelope isn't accessible in all mail setups. This test returns true if any combination of the header-list and values-list arguments match'''.'''<br />
<br />
|-<br />
| true<br />
| A test for a true result (can be used if an action command should be executed every time)'''.'''<br />
<br />
|-<br />
| not<br />
| Negates a given test'''.'''<br />
<br />
|-<br />
| size<br />
| Deals with the size of the mail'''.'''<br />
<br />
|-<br />
| currentdate<br />
| Compares a given date with the current date ('''available with 6.20''')<br />
<br />
|-<br />
| header<br />
| Tests against all headers of a mail. So with this test in contrast to the address test also fields such as subject can be handled. This test returns true if any combination of the header-list and values-list arguments match.<br />
<br />
|-<br />
| body<br />
| Tests against the content of a mail.<br />
<br />
|-<br />
| allof<br />
| Defines an AND condition between several tests'''.'''<br />
<br />
|-<br />
| anyof<br />
| Defines an OR condition between several tests'''.'''<br />
<br />
|}<br />
<center>''Table 2: List of all possible tests''</center><br />
<br />
<br />
{| id="Table 3" cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| is<br />
| If a field is equal to a given value<br />
<br />
|-<br />
| contains<br />
| If a field contains a given value at any position<br />
<br />
|-<br />
| matches<br />
| Tests if the value matches the value in the specified field. Here some wild cards can be used. "*" matches zero or more characters, and "?" matches a single character. To use the characters themselves they have to be escaped via a backslash.<br />
<br />
|-<br />
| regex<br />
| Tests if a given regular expression matches with the value present in the specified field.<br />
<br />
|-<br />
| user<br />
| Tests if the user part of an e-mail address is the value given here. This means in [mailto:herbert+mustermann@example.com herbert+mustermann@example.com]. The user checks the part herbert.<br />
<br />
'''Attention: '''This comparison can only be used in conjunction with the address test<br />
<br />
|-<br />
| detail<br />
| Tests if the detail part of an e-mail address is the value given here. In the example above this evaluates to mustermann.<br />
<br />
'''Attention: '''This comparison can only be used in conjunction with the address test<br />
<br />
|}<br />
<center>''Table 3: List of all possible comparisons''</center><br />
<br />
<br />
<br />
{| id="Table 4" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| address<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see [[#Table 26|Table 26]]).<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields. The test will be true if any of the strings matches<br />
<br />
|}<br />
<center>''Table 4: Structure of address-test''</center><br />
<br />
<br />
{| id="Table 5" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| envelope<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see [[#Table 26|Table 26]]).<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields. The test will be true if any of the strings matches<br />
<br />
|}<br />
<center>''Table 5: Structure of envelope-test''</center><br />
<br />
<br />
{| id="Table 6" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| true<br />
| A string describing the test command.<br />
<br />
|}<br />
<center>''Table 6: Structure of true-test''</center><br />
<br />
<br />
{| id="Table 7" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| not<br />
| A string describing the test command.<br />
<br />
|-<br />
| test<br />
| Object<br />
| <br />
| One of the test objects which result will be negated<br />
<br />
|}<br />
<center>''Table 7: Structure of not-test''</center><br />
<br />
<br />
{| id="Table 8" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| size<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Only two types are valid here. A description can be found in [[#Table 9|Table 9]].<br />
<br />
|-<br />
| size<br />
| Number<br />
| <br />
| A number specifying the size for this comparison, in bytes.<br />
<br />
|}<br />
<center>''Table 8: Structure of size-test''</center><br />
<br />
<br />
{| id="Table 9" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| over<br />
| Used in the size test to check for a value greater than the given one<br />
<br />
|-<br />
| under<br />
| Used in the size test to check for a value less than the given one<br />
<br />
|}<br />
<center>''Table 9: Types of comparison for size''</center><br />
<br />
<br />
<br />
{| id="currentdate" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| currentdate<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Only three types are valid here. A description can be found in [[#Table 11|Table 11]].<br />
<br />
|-<br />
| datepart<br />
| String<br />
| <br />
| A string containing the string "date" as we only allow fix date comparisions for now.<br />
<br />
|-<br />
| datevalue<br />
| Array<br />
| <br />
| A value array containing the corresponding value to the datepart. For "date" this will be an array of "Date". The test will be true if any of the values matches<br />
<br />
|}<br />
<center>''Table 10: Structure of currentdate-test''</center><br />
<br />
<br />
<br />
{| id="Table 11" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| is<br />
| Used in the date test to check for a value equal to the given one<br />
<br />
|-<br />
| ge<br />
| Used in the date test to check for a value greater or equal to the given one<br />
<br />
|-<br />
| le<br />
| Used in the date test to check for a value less or equal to the given one<br />
<br />
|}<br />
<center>''Table 11: Types of comparison for currentdate''</center><br />
<br />
<br />
<br />
{| id="Table 12" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| header<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see [[#Table 26|Table 26]])<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the values for the header fields. The test will be true if any of the strings matches<br />
<br />
|}<br />
<center>''Table 12: Structure of header-test''</center><br />
<br />
<br />
{| id="Table 13" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| body<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see [[#Table 26|Table 26]]).<br />
<br />
|-<br />
| extensionskey<br />
| String<br />
| <br />
| The extension key can be one of the value found in [[#Table 12|Table 12]]<br />
<br />
|-<br />
| extensionsvalue<br />
| String<br />
| <br />
| A value for the given key. If the key has no value (see [[#Table 12|Table 12]] for this information) the value given here is ignored<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the values for the body. The test will be true if any of the strings matches<br />
<br />
|}<br />
<center>''Table 13: Structure of body-test''</center><br />
<br />
<br />
{| id="Table 14" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| content<br />
| An extension used in conjunction with the body test to define the content which should be considered. This extension will need a parameter specifying the mime-type of the part of the message which will be searched.<br />
<br />
|-<br />
| text<br />
| An extension used in conjunction with the body test to define that only the text of the body should be considered in this test. This extension takes no parameter<br />
<br />
|}<br />
<center>''Table 14: List of possible extensions''</center><br />
<br />
<br />
{| id="Table 15" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| allof<br />
| A string describing the test command.<br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| A array of tests<br />
<br />
|}<br />
<center>''Table 15: Structure of allof-test''</center><br />
<br />
<br />
{| id="Table 16" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| anyof<br />
| A string describing the test command.<br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| A array of tests<br />
<br />
|}<br />
<center>''Table 16: Structure of anyof-test''</center><br />
<br />
== Actions ==<br />
In this section you will find the structures of all action commands which are specified until now. First a complete list of all action commands is given with a short description of them, later on the different objects for those commands are specified.<br />
<br />
<br />
{| id="Table 17" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| keep<br />
| Keeps a mail non changed<br />
<br />
|-<br />
| discard<br />
| Discards a mail without any processing<br />
<br />
|-<br />
| redirect<br />
| Redirects a mail to a given e-mail address<br />
<br />
|-<br />
| move<br />
| Moves a mail into a given subfolder. The syntax for the subfolder given here. Must be the correct syntax of the underlying IMAP-server. So it is up to the GUI to detect things such as altnamespace or unixhierarchysep.<br />
<br />
|-<br />
| reject<br />
| Rejects the mail with a given text<br />
<br />
|-<br />
| stop<br />
| Stops any further progressing of a mail<br />
<br />
|-<br />
| vacation<br />
| Creates a vacation mail<br />
<br />
|-<br />
| addflags<br />
| Adds flags to a mail<br />
<br />
|-<br />
| notify<br />
| adds a notification<br />
<br />
|-<br />
| pgp<br />
| encrypts a mail via pgp<br />
<br />
|}<br />
<center>''Table 17: List of possible action commands''</center><br />
<br />
<br />
{| id="Table 18" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| keep<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 18: Structure of keep-command''</center><br />
<br />
<br />
{| id="Table 19" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| discard<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 19: Structure of discard-command''</center><br />
<br />
<br />
{| id="Table 20" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| redirect<br />
| A string defining the object itself<br />
<br />
|-<br />
| to<br />
| String<br />
| <br />
| A string containing where the mail should be redirected to<br />
<br />
|}<br />
<center>''Table 20: Structure of redirect-command''</center><br />
<br />
<br />
{| id="Table 21" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| move<br />
| A string defining the object itself<br />
<br />
|-<br />
| into<br />
| String<br />
| <br />
| This string takes the object id of the destination mail folder as specified in the HTTP API of the groupware<br />
<br />
|}<br />
<center>''Table 21: Structure of move-command''</center><br />
<br />
<br />
{| id="Table 22" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| reject<br />
| A string defining the object itself<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| A string containing the reason why the mail is rejected<br />
<br />
|}<br />
<center>''Table 22: Structure of reject-command''</center><br />
<br />
<br />
{| id="Table 23" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| stop<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 23: Structure of stop-command''</center><br />
<br />
<br />
{| id="Table 24" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| vacation<br />
| A string defining the object itself<br />
<br />
|-<br />
| days<br />
| Integer<br />
| <br />
| The days for which a vacation text is returned<br />
<br />
|-<br />
| addresses<br />
| Array<br />
| <br />
| The addresses for which this vacation is responsible. That means for which addresses out of the aliases array of the user defining this filter, vacations will be sent.<br />
<br />
|-<br />
| subject<br />
| String<br />
| <br />
| The new subject for the returned message (can be left empty, when only adding RE:)<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| The vacation text itself<br />
<br />
|}<br />
<center>''Table 24: Structure of vacation-command''</center><br />
<br />
<br />
{| id="Table 25" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| addflags<br />
| A string defining the object itself<br />
<br />
|-<br />
| flags<br />
| Array<br />
| <br />
| An array containing the flags which should be added to that mail. A flag can be either a system flag or a user flag. System flags begin with a backslash (\) and can be one of the following:<br />
* \seen<br />
* \answered<br />
* \flagged<br />
* \deleted<br />
* \draft<br />
* \recent<br />
System flags are case-insensitive.<br />
<br />
User flags begin with a dollar sign ($) and can contain any ASCII characters between 0x21 (!) and 0x7E (~), inclusive, except for the characters 0x22, 0x25, 0x28, 0x29, 0x2A, 0x5C, 0x5D and 0x7B, which correspond to<br />
"%()*\]{<br />
Mail color flags as used by OX are implemented by user flags of the form $cl_''n'', where ''n'' is a number between 1 and 10, includive.<br />
<br />
See RFC 3501 for further details on IMAP flags and their meanings.<br />
|}<br />
<center>''Table 25: Structure of addflags-command''</center><br />
<br />
{| id="Table 26" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| notify<br />
| A string defining the object itself<br />
<br />
|-<br />
| message<br />
| String<br />
| <br />
| the content of the notification message<br />
<br />
|-<br />
| method<br />
| String<br />
| <br />
| the method of the notification message, e.g. <pre>"mailto:012345678@sms.gateway"</pre><br />
<br />
|}<br />
<center>''Table 26: Structure of notify-command''</center><br />
<br />
{| id="Table 27" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| pgp<br />
| A string defining the object itself<br />
<br />
|-<br />
| keys<br />
| Array<br />
| <br />
| The public keys as string which should be used for encryption<br />
<br />
|}<br />
<center>''Table 27: Structure of pgp-command''</center><br />
<br />
= Requests =<br />
== Get the configuration of the mail filter backend ==<br />
<tt>GET /ajax/mailfilter?action=config</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Response body: An object describing the configuration like described in [[#Table 28|Table 28]].<br />
<br />
<br />
{| id="Table 28" cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| An array containing test-objects like described in [[#Table 29|Table 29]]<br />
<br />
|-<br />
| actioncommands<br />
| Array<br />
| <br />
| An array containing the valid action commands as strings. A list of all possible values can be found in [[#Table 15|Table 15]].<br />
<br />
|}<br />
<center>''Table 28: Config object''</center><br />
<br />
<br />
{| id="Table 29" cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| test<br />
| String<br />
| <br />
| A name for the test. A list of all possible tests can be found in [[#Table 2|Table 2]]. The corresponding objects can be used in the test field in [[#Table 1|Table 1]].<br />
<br />
|-<br />
| comparison<br />
| Array<br />
| <br />
| A string array containing the valid comparison types for this test. Possible values are given in [[#Table 3|Table 3]]. Values given in this array can be used in the comparison field in <br />
<br />
|}<br />
<center>''Table 29: Test object''</center><br />
<br />
== Get all mail filter rules ==<br />
<tt>GET /ajax/mailfilter?action=list</tt><br />
<br />
Parameters:<br />
<br />
* <tt>flag</tt> If given, only rules with this flag are returned<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Response body: An array of rule objects like described in [[#Table 1|Table 1]].<br />
<br />
== Create a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=new</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Request body: Rule object as described in [[#Table 1|Table 1]]. If the field <tt>position</tt> is included in [[#Table 1|Table 1]] it's taken as the position of the rule in the array on the server side. Note that this value shouldn't be greater than the size of all rules<br />
<br />
Response body: An integer for the id of the new created rule.<br />
<br />
== Delete a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=delete</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Request body: An object with the field <tt>id</tt>.<br />
<br />
== Reorder mail filter rules ==<br />
PUT <tt>/ajax/mailfilter?action=reorder</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Request body: An array of unique ids which represents how the rule with the corresponding unique ids are ordered<br />
<br />
== Update a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=update</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Request body: Rule object as described in [[#Table 1|Table 1]] with the <tt>id</tt> set (which identifies the rule to change). Only modified fields are present.<br />
<br />
== Delete the whole script ==<br />
PUT <tt>/ajax/mailfilter?action=deletescript</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Note that this call is only used as workaround for parsing errors in the backend, so that the user is able to kick a whole script if it contains errors in the grammar.<br />
<br />
== Get the whole script ==<br />
PUT <tt>/ajax/mailfilter?action=getscript</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Response body: A text of the complete sieve script<br />
<br />
Note that this call is only used as workaround for parsing errors in the backend, so that the user is able to get the plaintext of a complete script.</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=HTTP_API_MailFilter&diff=16968HTTP API MailFilter2014-02-03T16:33:29Z<p>Dennis Sieben: /* Actions */</p>
<hr />
<div><center>'''Open-Xchange Mail Filter HTTP API'''</center><br />
<br />
= Introduction =<br />
This document describes only the mail filter HTTP-API. So it's only a part which must be embedded into something which counts for login/logout, session handling and low-level protocol issues such as error handling. At the moment this will be the groupware server. So the modules needed for basic operations can be found there.<br />
<br />
= Module mailfilter =<br />
This module is used to access all mail filter related options.<br />
<br />
First of all the main structure of a mail filter script is, that it has different rules. Each of them contains one command. This command takes a test condition which executes the actions given in that command if the test condition is true.<br />
<br />
The test condition consists of a test command and some arguments for this command depending on the command itself. Because the available tests depend on the mail filter server, these tests must be determined at runtime. So that no test field is transferred to the server which it isn't able to handle. Examples for tests are <tt>address</tt>, <tt>allof</tt> and <tt>anyof</tt>.<br />
<br />
Each test has a special comparison. The list of available comparisons depends on the test given and the mail filter server configuration so they have to be determined at runtime too.<br />
<br />
Each time you want to do some action on a mail you need a so called action command. This describes what to do with a mail. To action commands the same applies as to the test commands and their comparison types, they must be determined at runtime.<br />
<br />
All those dynamical values can be fetched via a config object at startup. This object shows the capabilities of the server to the client. This allows the client to show only the capabilities the server actually has to the user and to send only objects to the server which produce no errors on the server side.<br />
<br />
To deal with this high flexibility of mail filters this specification can be roughly divided into 2 parts. A non-changing core and dynamical extensions. The core specification is that each rule consists of a name, an ID, a value showing if this rule is active or not and a tag which can be set on a rule to mark that rule for a special purpose. Furthermore each rule takes a test object, specifying in what case the following actions are triggered, and one or many actioncommands, specifying the actions itself. For a detailed specification see [[#Table 1|Table 1]].<br />
<br />
The objects for the tests and the actions are dynamical, so the set presented in this specification may be changed over the time, but only compatible changes are allowed to the objects, otherwise new test or action objects have to be introduced. Due to the fact that not every sieve implementation will offer all the capabilities written in this document, the server will sent his configuration if a special request is made. This configuration will show which of the tests and which of the actions are allowed. So for example if the server signals that it is capable of handling vacation, sending a vacation object as action is safe.<br />
<br />
Furthermore some tests use a comparison field as stated above which specifies how the fields are compared. The values of this field must also be determined at runtime. So in the configuration object there is a special part which shows the comparisons which are available. Note that not all comparisons can be used with every test. Some of them are denoted to a special test, which can be found in the [[#Table 3|Table 3]].<br />
<br />
= The core =<br />
As written in the introduction the main part of a mail filter are the rules. A rule object will always have the structure you can see in the table below ([[#Table 1|Table 1]]). The dynamical parts are the test, which are represented by different options, see [[#Tests|4.1. Tests]], and the actions, also represented in [[#Actions|4.2. Actions]]. Note that the test and actioncmds fields and the text and errormsg fields are mutual exclusive. So if test and actioncmds fields are filled the text and errormsg fields are not present and vice versa.<br />
<br />
{| id="Table 1" cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| Integer<br />
| <br />
| A unique identifier (once created must not be changed)<br />
<br />
|-<br />
| position<br />
| Integer<br />
| <br />
| The position inside the mail filter list. Starts with 0<br />
<br />
|-<br />
| rulename<br />
| String<br />
| <br />
| A name describing the rule, can be empty but must not contain a line break<br />
<br />
|-<br />
| active<br />
| Boolean<br />
| <br />
| If this rule is active or not<br />
<br />
|-<br />
| flags<br />
| Array<br />
| <br />
| A string array containing flags which are set on this rule. Each flag can only contain the following characters: 1-9 a-z A-Z. Currently 2 flags are reserved here: "spam" which marks the default spam rule and "vacation" which marks the vacation rules.<br />
<br />
|-<br />
| test<br />
| Object<br />
| <br />
| The structure of the different test objects can be found in section [[#Tests|4.1. Tests]]. The valid tests in the current setup can be found in the configuration object <br />
<br />
|-<br />
| actioncmds<br />
| Array<br />
| <br />
| An array of action objects whose different structures can be found in section [[#Actions|4.2. Actions]]. The action commands which are valid here can be determined through the config object see Table 24<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| If this rule cannot be read in this string is filled containing the whole lines of this command.<br />
<br />
|-<br />
| errormsg<br />
| String<br />
| <br />
| If this rule cannot be read in this string is filled containing a message why, or what part of the rule isn't known<br />
<br />
|}<br />
<center>''Table 1: Structure of a rule''</center><br />
<br />
= The dynamical part =<br />
== Tests ==<br />
In this section you will find the structures of all test commands which are specified until now. First a complete list of all test commands is given with a short description of them, afterwards a complete list of all comparison as they belong to the test section. Finally the different objects for those test commands are specified.<br />
<br />
<br />
{| id="Table 2" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| address<br />
| This test type applies to addresses only. So it may be used for all header fields which contain addresses. This test returns true if any combination of the header-list and values-list arguments match.<br />
<br />
|-<br />
| envelope<br />
| This test applies to the envelope of a mail. This test isn't used under normal circumstances as the envelope isn't accessible in all mail setups. This test returns true if any combination of the header-list and values-list arguments match'''.'''<br />
<br />
|-<br />
| true<br />
| A test for a true result (can be used if an action command should be executed every time)'''.'''<br />
<br />
|-<br />
| not<br />
| Negates a given test'''.'''<br />
<br />
|-<br />
| size<br />
| Deals with the size of the mail'''.'''<br />
<br />
|-<br />
| currentdate<br />
| Compares a given date with the current date ('''available with 6.20''')<br />
<br />
|-<br />
| header<br />
| Tests against all headers of a mail. So with this test in contrast to the address test also fields such as subject can be handled. This test returns true if any combination of the header-list and values-list arguments match.<br />
<br />
|-<br />
| body<br />
| Tests against the content of a mail.<br />
<br />
|-<br />
| allof<br />
| Defines an AND condition between several tests'''.'''<br />
<br />
|-<br />
| anyof<br />
| Defines an OR condition between several tests'''.'''<br />
<br />
|}<br />
<center>''Table 2: List of all possible tests''</center><br />
<br />
<br />
{| id="Table 3" cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| is<br />
| If a field is equal to a given value<br />
<br />
|-<br />
| contains<br />
| If a field contains a given value at any position<br />
<br />
|-<br />
| matches<br />
| Tests if the value matches the value in the specified field. Here some wild cards can be used. "*" matches zero or more characters, and "?" matches a single character. To use the characters themselves they have to be escaped via a backslash.<br />
<br />
|-<br />
| regex<br />
| Tests if a given regular expression matches with the value present in the specified field.<br />
<br />
|-<br />
| user<br />
| Tests if the user part of an e-mail address is the value given here. This means in [mailto:herbert+mustermann@example.com herbert+mustermann@example.com]. The user checks the part herbert.<br />
<br />
'''Attention: '''This comparison can only be used in conjunction with the address test<br />
<br />
|-<br />
| detail<br />
| Tests if the detail part of an e-mail address is the value given here. In the example above this evaluates to mustermann.<br />
<br />
'''Attention: '''This comparison can only be used in conjunction with the address test<br />
<br />
|}<br />
<center>''Table 3: List of all possible comparisons''</center><br />
<br />
<br />
<br />
{| id="Table 4" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| address<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see [[#Table 26|Table 26]]).<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields. The test will be true if any of the strings matches<br />
<br />
|}<br />
<center>''Table 4: Structure of address-test''</center><br />
<br />
<br />
{| id="Table 5" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| envelope<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see [[#Table 26|Table 26]]).<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields. The test will be true if any of the strings matches<br />
<br />
|}<br />
<center>''Table 5: Structure of envelope-test''</center><br />
<br />
<br />
{| id="Table 6" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| true<br />
| A string describing the test command.<br />
<br />
|}<br />
<center>''Table 6: Structure of true-test''</center><br />
<br />
<br />
{| id="Table 7" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| not<br />
| A string describing the test command.<br />
<br />
|-<br />
| test<br />
| Object<br />
| <br />
| One of the test objects which result will be negated<br />
<br />
|}<br />
<center>''Table 7: Structure of not-test''</center><br />
<br />
<br />
{| id="Table 8" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| size<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Only two types are valid here. A description can be found in [[#Table 9|Table 9]].<br />
<br />
|-<br />
| size<br />
| Number<br />
| <br />
| A number specifying the size for this comparison, in bytes.<br />
<br />
|}<br />
<center>''Table 8: Structure of size-test''</center><br />
<br />
<br />
{| id="Table 9" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| over<br />
| Used in the size test to check for a value greater than the given one<br />
<br />
|-<br />
| under<br />
| Used in the size test to check for a value less than the given one<br />
<br />
|}<br />
<center>''Table 9: Types of comparison for size''</center><br />
<br />
<br />
<br />
{| id="currentdate" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| currentdate<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Only three types are valid here. A description can be found in [[#Table 11|Table 11]].<br />
<br />
|-<br />
| datepart<br />
| String<br />
| <br />
| A string containing the string "date" as we only allow fix date comparisions for now.<br />
<br />
|-<br />
| datevalue<br />
| Array<br />
| <br />
| A value array containing the corresponding value to the datepart. For "date" this will be an array of "Date". The test will be true if any of the values matches<br />
<br />
|}<br />
<center>''Table 10: Structure of currentdate-test''</center><br />
<br />
<br />
<br />
{| id="Table 11" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| is<br />
| Used in the date test to check for a value equal to the given one<br />
<br />
|-<br />
| ge<br />
| Used in the date test to check for a value greater or equal to the given one<br />
<br />
|-<br />
| le<br />
| Used in the date test to check for a value less or equal to the given one<br />
<br />
|}<br />
<center>''Table 11: Types of comparison for currentdate''</center><br />
<br />
<br />
<br />
{| id="Table 12" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| header<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see [[#Table 26|Table 26]])<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the values for the header fields. The test will be true if any of the strings matches<br />
<br />
|}<br />
<center>''Table 12: Structure of header-test''</center><br />
<br />
<br />
{| id="Table 13" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| body<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see [[#Table 26|Table 26]]).<br />
<br />
|-<br />
| extensionskey<br />
| String<br />
| <br />
| The extension key can be one of the value found in [[#Table 12|Table 12]]<br />
<br />
|-<br />
| extensionsvalue<br />
| String<br />
| <br />
| A value for the given key. If the key has no value (see [[#Table 12|Table 12]] for this information) the value given here is ignored<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the values for the body. The test will be true if any of the strings matches<br />
<br />
|}<br />
<center>''Table 13: Structure of body-test''</center><br />
<br />
<br />
{| id="Table 14" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| content<br />
| An extension used in conjunction with the body test to define the content which should be considered. This extension will need a parameter specifying the mime-type of the part of the message which will be searched.<br />
<br />
|-<br />
| text<br />
| An extension used in conjunction with the body test to define that only the text of the body should be considered in this test. This extension takes no parameter<br />
<br />
|}<br />
<center>''Table 14: List of possible extensions''</center><br />
<br />
<br />
{| id="Table 15" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| allof<br />
| A string describing the test command.<br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| A array of tests<br />
<br />
|}<br />
<center>''Table 15: Structure of allof-test''</center><br />
<br />
<br />
{| id="Table 16" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| anyof<br />
| A string describing the test command.<br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| A array of tests<br />
<br />
|}<br />
<center>''Table 16: Structure of anyof-test''</center><br />
<br />
== Actions ==<br />
In this section you will find the structures of all action commands which are specified until now. First a complete list of all action commands is given with a short description of them, later on the different objects for those commands are specified.<br />
<br />
<br />
{| id="Table 17" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| keep<br />
| Keeps a mail non changed<br />
<br />
|-<br />
| discard<br />
| Discards a mail without any processing<br />
<br />
|-<br />
| redirect<br />
| Redirects a mail to a given e-mail address<br />
<br />
|-<br />
| move<br />
| Moves a mail into a given subfolder. The syntax for the subfolder given here. Must be the correct syntax of the underlying IMAP-server. So it is up to the GUI to detect things such as altnamespace or unixhierarchysep.<br />
<br />
|-<br />
| reject<br />
| Rejects the mail with a given text<br />
<br />
|-<br />
| stop<br />
| Stops any further progressing of a mail<br />
<br />
|-<br />
| vacation<br />
| Creates a vacation mail<br />
<br />
|-<br />
| addflags<br />
| Adds flags to a mail<br />
<br />
|-<br />
| notify<br />
| adds a notification<br />
<br />
|-<br />
| pgp<br />
| encrypts a mail via pgp<br />
<br />
|}<br />
<center>''Table 17: List of possible action commands''</center><br />
<br />
<br />
{| id="Table 18" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| keep<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 18: Structure of keep-command''</center><br />
<br />
<br />
{| id="Table 19" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| discard<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 19: Structure of discard-command''</center><br />
<br />
<br />
{| id="Table 20" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| redirect<br />
| A string defining the object itself<br />
<br />
|-<br />
| to<br />
| String<br />
| <br />
| A string containing where the mail should be redirected to<br />
<br />
|}<br />
<center>''Table 20: Structure of redirect-command''</center><br />
<br />
<br />
{| id="Table 21" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| move<br />
| A string defining the object itself<br />
<br />
|-<br />
| into<br />
| String<br />
| <br />
| This string takes the object id of the destination mail folder as specified in the HTTP API of the groupware<br />
<br />
|}<br />
<center>''Table 21: Structure of move-command''</center><br />
<br />
<br />
{| id="Table 22" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| reject<br />
| A string defining the object itself<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| A string containing the reason why the mail is rejected<br />
<br />
|}<br />
<center>''Table 22: Structure of reject-command''</center><br />
<br />
<br />
{| id="Table 23" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| stop<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 23: Structure of stop-command''</center><br />
<br />
<br />
{| id="Table 24" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| vacation<br />
| A string defining the object itself<br />
<br />
|-<br />
| days<br />
| Integer<br />
| <br />
| The days for which a vacation text is returned<br />
<br />
|-<br />
| addresses<br />
| Array<br />
| <br />
| The addresses for which this vacation is responsible. That means for which addresses out of the aliases array of the user defining this filter, vacations will be sent.<br />
<br />
|-<br />
| subject<br />
| String<br />
| <br />
| The new subject for the returned message (can be left empty, when only adding RE:)<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| The vacation text itself<br />
<br />
|}<br />
<center>''Table 24: Structure of vacation-command''</center><br />
<br />
<br />
{| id="Table 25" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| addflags<br />
| A string defining the object itself<br />
<br />
|-<br />
| flags<br />
| Array<br />
| <br />
| An array containing the flags which should be added to that mail. A flag can be either a system flag or a user flag. System flags begin with a backslash (\) and can be one of the following:<br />
* \seen<br />
* \answered<br />
* \flagged<br />
* \deleted<br />
* \draft<br />
* \recent<br />
System flags are case-insensitive.<br />
<br />
User flags begin with a dollar sign ($) and can contain any ASCII characters between 0x21 (!) and 0x7E (~), inclusive, except for the characters 0x22, 0x25, 0x28, 0x29, 0x2A, 0x5C, 0x5D and 0x7B, which correspond to<br />
"%()*\]{<br />
Mail color flags as used by OX are implemented by user flags of the form $cl_''n'', where ''n'' is a number between 1 and 10, includive.<br />
<br />
See RFC 3501 for further details on IMAP flags and their meanings.<br />
|}<br />
<center>''Table 25: Structure of addflags-command''</center><br />
<br />
{| id="Table 26" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| notify<br />
| A string defining the object itself<br />
<br />
|-<br />
| message<br />
| String<br />
| <br />
| the content of the notification message<br />
<br />
|-<br />
| method<br />
| String<br />
| <br />
| the method of the notification message, e.g. <pre>"mailto:012345678@sms.gateway"</pre><br />
<br />
|}<br />
<center>''Table 26: Structure of notify-command''</center><br />
<br />
{| id="Table 27" cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| pgp<br />
| A string defining the object itself<br />
<br />
|-<br />
| keys<br />
| Array<br />
| <br />
| The public keys as string which should be used for encryption<br />
<br />
|}<br />
<center>''Table 27: Structure of pgp-command''</center><br />
<br />
= Requests =<br />
== Get the configuration of the mail filter backend ==<br />
<tt>GET /ajax/mailfilter?action=config</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Response body: An object describing the configuration like described in [[#Table 26|Table 26]].<br />
<br />
<br />
{| id="Table 26" cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| An array containing test-objects like described in [[#Table 27|Table 27]]<br />
<br />
|-<br />
| actioncommands<br />
| Array<br />
| <br />
| An array containing the valid action commands as strings. A list of all possible values can be found in [[#Table 15|Table 15]].<br />
<br />
|}<br />
<center>''Table 26: Config object''</center><br />
<br />
<br />
{| id="Table 27" cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| test<br />
| String<br />
| <br />
| A name for the test. A list of all possible tests can be found in [[#Table 2|Table 2]]. The corresponding objects can be used in the test field in [[#Table 1|Table 1]].<br />
<br />
|-<br />
| comparison<br />
| Array<br />
| <br />
| A string array containing the valid comparison types for this test. Possible values are given in [[#Table 3|Table 3]]. Values given in this array can be used in the comparison field in <br />
<br />
|}<br />
<center>''Table 27: Test object''</center><br />
<br />
== Get all mail filter rules ==<br />
<tt>GET /ajax/mailfilter?action=list</tt><br />
<br />
Parameters:<br />
<br />
* <tt>flag</tt> If given, only rules with this flag are returned<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Response body: An array of rule objects like described in [[#Table 1|Table 1]].<br />
<br />
== Create a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=new</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Request body: Rule object as described in [[#Table 1|Table 1]]. If the field <tt>position</tt> is included in [[#Table 1|Table 1]] it's taken as the position of the rule in the array on the server side. Note that this value shouldn't be greater than the size of all rules<br />
<br />
Response body: An integer for the id of the new created rule.<br />
<br />
== Delete a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=delete</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Request body: An object with the field <tt>id</tt>.<br />
<br />
== Reorder mail filter rules ==<br />
PUT <tt>/ajax/mailfilter?action=reorder</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Request body: An array of unique ids which represents how the rule with the corresponding unique ids are ordered<br />
<br />
== Update a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=update</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Request body: Rule object as described in [[#Table 1|Table 1]] with the <tt>id</tt> set (which identifies the rule to change). Only modified fields are present.<br />
<br />
== Delete the whole script ==<br />
PUT <tt>/ajax/mailfilter?action=deletescript</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Note that this call is only used as workaround for parsing errors in the backend, so that the user is able to kick a whole script if it contains errors in the grammar.<br />
<br />
== Get the whole script ==<br />
PUT <tt>/ajax/mailfilter?action=getscript</tt><br />
<br />
Parameters:<br />
<br />
* <tt>username</tt> This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed<br />
<br />
Response body: A text of the complete sieve script<br />
<br />
Note that this call is only used as workaround for parsing errors in the backend, so that the user is able to get the plaintext of a complete script.</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Tutorial_10K&diff=16933AppSuite:OX Tutorial 10K2014-01-30T15:38:41Z<p>Dennis Sieben: /* Recommended Optional Next Steps */</p>
<hr />
<div>= Tutorial: OX AppSuite Setup for up to 10.000 users =<br />
<br />
'''This article describes what you need for a typical OX AppSuite Setup for up to 10.000 Users with minimal efforts.'''<br />
<br />
It contains everything you need to:<br />
* Understand the design of the OX AppSuite setup including additional services<br />
* Install the whole system based on the relevant articles<br />
* Find pointers to the next steps of integration<br />
<br />
<br />
= System Design =<br />
<br />
[[Image:AppSuite-10k.png|frameless|alt=Architecture-10k|800px]]<br />
<br />
The system is designed to provide maximum functionality with a minimum of necessary hardware. All OX services are running on one single machine.<br />
<br />
<br />
== Core Components for OX AppSuite ==<br />
<br />
* One OX AppSuite server (HW recommendation: 16GB RAM / 4 cores)<br />
* MySQL installed directly on this server <br />
* Optional: NFS Server to store documents and files<br />
<br />
<br />
== Infrastructure Components not delivered by OX ==<br />
<br />
* An email system providing IMAP and SMTP<br />
* A control panel for creation and administration of users<br />
<br />
= Overview Installation Steps =<br />
<br />
'''To deploy the described OX setup, the following steps need to be done. '''<br />
<br />
<br />
== Mandatory Steps ==<br />
# Initialize and configure MySQL database<br />
# Install and configure OX service<br />
<br />
== Steps depending on your environment ==<br />
# Connect Control Panel<br />
# Connect Email System<br />
<br />
== Recommended Optional Next Steps ==<br />
# Automated Frontend Tests (see [[Automated_GUI_Tests|here]])<br />
# Upsell Plugin (see [[AppSuite:Upsell|here]] and [[AppSuite:Upsell_tools|here]])<br />
# Automatic FailOver<br />
# Theming (see [[AppSuite:Theming|here]])<br />
<br />
= Mandatory Installation Steps - Instructions & Recommendations =<br />
<br />
<br />
'''The following steps need to be done in every case to get OX up and running:'''<br />
<br />
== Install and configure OX ==<br />
<br />
OX will be installed on the server.<br />
<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_6.0|Download and Installation Guide for Debian GNU/Linux 6.0 (Squeeze)]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_7.0|Download and Installation Guide for Debian GNU/Linux 7.0 (Wheezy)]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_SLES11|Download and Installation Guide for SUSE Linux Enterprise Server 11]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_RHEL6|Download and Installation Guide for RedHat Enterprise Linux 6]]<br />
<br />
You also should install and configure the OXtender for Business Mobility<br />
<br />
[[AppSuite:OXtender_for_Business_Mobility_Installation_Guide|Installation of the OXtender for Business Mobility]]<br />
<br />
Let your users connect to their data from other services like Facebook, Twitter or LinkedIn by configuring the "SocialOX"<br />
<br />
[[SocialOX|SocialOX-Configuration]]<br />
<br />
= Installation Steps depending on your environment - Instructions & Recommendations =<br />
<br />
'''The following components need to be implemented in your environment.'''<br />
<br />
<br />
{{OX_HE_Tutorial_CP}}<br />
<br />
<br />
{{OX_HE_Tutorial_HGP}}<br />
<br />
<br />
{{OX_HE_Tutorial_Plesk}}<br />
<br />
<br />
{{OX_HE_Tutorial_Auth}}<br />
<br />
<br />
== Connect Email System ==<br />
<br />
Every email system providing IMAP and SMTP can be used as backend to OX. Best experiences are made with the widespread Linux based IMAP servers [http://dovecot.org/ Dovecot], [http://www.cyrusimap.org/ Cyrus] or [http://www.courier-mta.org/imap/ Courier]. <br />
<br />
Other IMAP servers need to be tested thoroughly before going into production.<br />
<br />
There are several possibilities to implement the Email system:<br />
<br />
# You already have an email system available: Nothing needs to be done, it just needs to be configured<br />
# You use Plesk Panel: Nothing special needs to be done, everything you need is contained in the OXtender for Plesk<br />
# You want to setup a new Email system: It is recommended to use Dovecot, as this is very stable, fast, feature rich and easy to scale<br />
<br />
<br />
{{OX_HE_Tutorial_Dovecot}}<br />
<br />
<br />
{{AppSuite:OX_Tutorial_Next}}</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Tutorial_100K&diff=16932AppSuite:OX Tutorial 100K2014-01-30T15:38:17Z<p>Dennis Sieben: /* Recommended Optional Next Steps */</p>
<hr />
<div>= Tutorial: High Available OX AppSuite Setup for up to 100.000 users =<br />
<br />
'''This article describes what you need for a typical OX AppSuite Setup for up to 100.000 Users, which is fully clustered and high available.'''<br />
<br />
It contains everything you need to:<br />
* Understand the design of the OX AppSuite setup including additional services<br />
* Install the whole system based on the relevant articles<br />
* Find pointers to the next steps of integration<br />
<br />
<br />
= System Design =<br />
<br />
[[Image:AppSuite-100k.png|800px]]<br />
<br />
The system is designed to provide maximum functionality and availability with a minimum of necessary hardware. If the services on one server fail, it is enough to take over the IP address to the other machine and service will stay up and running.<br />
<br />
== Core Components for OX AppSuite ==<br />
<br />
* Two OX AppSuite servers (HW recommendation: 16GB RAM / 4 cores each)<br />
* MySQL installed directly on these server <br />
* NFS Server to store documents and files<br />
<br />
== Infrastructure Components not delivered by OX ==<br />
<br />
* An email system providing IMAP and SMTP<br />
* A control panel for creation and administration of users<br />
* A Load Balancer in front of the OX servers (optional, recommended)<br />
<br />
= Overview Installation Steps =<br />
<br />
'''To deploy the described OX setup, the following steps need to be done. '''<br />
<br />
<br />
== Mandatory Steps ==<br />
# Initialize and configure MySQL database on both servers<br />
# Install and configure OX on both servers<br />
<br />
== Steps depending on your environment ==<br />
# Implement Load Balancer<br />
# Connect Control Panel<br />
# Connect Email System<br />
<br />
== Recommended Optional Next Steps ==<br />
# Automated Frontend Tests (see [[Automated_GUI_Tests|here]])<br />
# Upsell Plugin (see [[AppSuite:Upsell|here]] and [[AppSuite:Upsell_tools|here]])<br />
# Automatic FailOver<br />
# Theming (see [[AppSuite:Theming|here]])<br />
<br />
= Mandatory Installation Steps - Instructions & Recommendations =<br />
<br />
<br />
'''The following steps need to be done in every case to get OX up and running:'''<br />
<br />
== Initialize and configure MySQL database on both servers ==<br />
<br />
MySQL will run on both servers. MySQL will be configured as Master-Master configuration to ensure data consistency on both servers.<br />
If one machine fails, the other machine will take over all functionality.<br />
<br />
[[OXLoadBalancingClustering_Database|Database setup for clustered environments]]<br />
<br />
== Install and configure OX on both servers ==<br />
<br />
OX will be installed on both servers. It will be configured to '''write''' to the '''first''' MySQL database and to '''read''' from the '''second''' MySQL database. This will distribute the load during normal operation as smooth as possible. During FailOver the IP address of the failed server will be taken over to the working server, the system stays operable.<br />
<br />
[[AppSuite:OXLoadBalancingClustering_OXConfiguration|Open-Xchange setup and configuration for clustered environments]]<br />
<br />
The NFS server will be mounted on both machines and registered as filestore.<br />
<br />
[[OXLoadBalancingClustering_Filestore|Filestore setup for clustered environments]]<br />
<br />
When multiple Open-Xchange Servers are configured within a cluster Session and Loadbalancing needs to be set up.<br />
<br />
[[OXLoadBalancingClustering_SessionLoadbalancing|Session and Loadbalancing for clustered environments]]<br />
<br />
[[OXLoadBalancingClustering_NetworkConfiguration|Network configuration for clustered environments]]<br />
<br />
You also should install and configure the OXtender for Business Mobility<br />
<br />
[[OXtender_for_Business_Mobility_Installation_Guide|Installation of the OXtender for Business Mobility]]<br />
<br />
Let your users connect to their data from other services like Facebook, Twitter or LinkedIn by configuring the "SocialOX"<br />
<br />
[[SocialOX|SocialOX-Configuration]]<br />
<br />
= Installation Steps depending on your environment - Instructions & Recommendations =<br />
<br />
'''The following components need to be implemented in your environment.'''<br />
<br />
<br />
== Implement Load Balancer ==<br />
<br />
A load balancer in front of the OX servers is recommended, but optional in this deployment size. (In small environments, DNS Round Robin may be sufficient).<br />
<br />
If you already have a hardware load balancing solution in place, this can be used. OX is known to work with the standard load balancing solutions from BigIP, Barracuda, Foundry, ...<br />
<br />
If you do not have a load balancing solution already in place, we recommend to use [http://www.keepalived.org/ Keepalived] as reliable and cost effective solution.<br />
<br />
Read more about configuring [[Keepalived | Keepalived for Open-Xchange]]<br />
<br />
<br />
{{OX_HE_Tutorial_CP}}<br />
<br />
<br />
{{OX_HE_Tutorial_HGP}}<br />
<br />
<br />
{{OX_HE_Tutorial_POA}}<br />
<br />
<br />
{{OX_HE_Tutorial_Auth}}<br />
<br />
<br />
== Connect Email System ==<br />
<br />
Every email system providing IMAP and SMTP can be used as backend to OX. Best experiences are made with the widespread Linux based IMAP servers [http://dovecot.org/ Dovecot], [http://www.cyrusimap.org/ Cyrus] or [http://www.courier-mta.org/imap/ Courier]. <br />
<br />
Other IMAP servers need to be tested thoroughly before going into production.<br />
<br />
There are several possibilities to implement the Email system:<br />
<br />
# You already have an email system available: Nothing needs to be done, it just needs to be configured<br />
# You use Parallels Automation (POA): Nothing special needs to be done, everything you need is contained in the APS package<br />
# You want to setup a new Email system: It is recommended to use Dovecot, as this is very stable, fast, feature rich and easy to scale<br />
<br />
<br />
{{OX_HE_Tutorial_Dovecot}}<br />
<br />
<br />
{{AppSuite:OX_Tutorial_Next}}<br />
<br />
<br />
{{OX_HE_Tutorial_FailOver}}</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Tutorial_1M&diff=16931AppSuite:OX Tutorial 1M2014-01-30T15:37:29Z<p>Dennis Sieben: /* Recommended Optional Next Steps */</p>
<hr />
<div>= Tutorial: High Available OX App Suite Setup for up to 1 Milion users =<br />
<br />
'''This article describes what you need for a typical OX App Suite Setup for up to 1.000.000 Users, which is fully clustered, high available and scaling very flexible.'''<br />
<br />
It contains everything you need to:<br />
* Understand the design of the OX App Suite setup including additional services<br />
* Install the whole system based on the relevant articles<br />
* Find pointers to the next steps of integration<br />
<br />
<br />
= System Design =<br />
<br />
[[Image:AppSuite-1M.png|1000px]]<br />
<br />
The system is designed to provide maximum functionality and availability with a minimum of necessary hardware. If the services on one OX server fail, this is transparently handled by the load balancer. If one MySQL server fails, it is sufficient to take over the IP address on the other MySQL server in the cluster to stay fully in operation.<br />
<br />
== General recommendations ==<br />
<br />
* A virtualisation enviroment is recommended<br />
* Many machines with less memory (16 GB) are preferred to fewer machines with big memory<br />
* The picture above shows a valid setup for a webmail only system. Further features like the Business Mobility Connector or OX Documentes require more ressources.<br />
<br />
== Infrastructure Components not delivered by OX ==<br />
<br />
* An email system providing IMAP and SMTP<br />
* A control panel for creation and administration of users<br />
* A Load Balancer in front of the OX servers (optional, recommended)<br />
<br />
= Overview Installation Steps =<br />
<br />
'''To deploy the described OX setup, the following steps need to be done. '''<br />
<br />
<br />
== Mandatory Steps ==<br />
# Initialize and configure MySQL database servers<br />
# Install and configure OX on all servers<br />
<br />
== Steps depending on your environment ==<br />
# Implement Load Balancer<br />
# Connect Control Panel<br />
# Connect Email System<br />
<br />
== Recommended Optional Next Steps ==<br />
# Automated Frontend Tests (see [[Automated_GUI_Tests|here]])<br />
# Upsell Plugin (see [[AppSuite:Upsell|here]] and [[AppSuite:Upsell_tools|here]])<br />
# Automatic FailOver<br />
# Theming (see [[AppSuite:Theming|here]])<br />
<br />
= Mandatory Installation Steps - Instructions & Recommendations =<br />
<br />
<br />
'''The following steps need to be done in every case to get OX up and running:'''<br />
<br />
== Initialize and configure MySQL database on both servers ==<br />
<br />
MySQL will be configured as Master-Master configuration to ensure data consistency on both servers.<br />
If one machine fails, the other machine will take over all functionality.<br />
<br />
[[OXLoadBalancingClustering_Database|Database setup for clustered environments]]<br />
<br />
== Install and configure OX on both servers ==<br />
<br />
OX will be installed on minimum two servers. It will be configured to '''write''' to the '''first''' MySQL database and to '''read''' from the '''second''' MySQL database in one cluster. This will distribute the load during normal operation as smooth as possible. During FailOver the IP address of the failed MySQL server will be taken over to the working server, the system stays operable.<br />
<br />
[[AppSuite:OXLoadBalancingClustering_OXConfiguration|Open-Xchange setup and configuration for clustered environments]]<br />
<br />
The NFS server will be mounted on all machines and registered as filestore.<br />
<br />
[[OXLoadBalancingClustering_Filestore|Filestore setup for clustered environments]]<br />
<br />
When multiple Open-Xchange Servers are configured within a cluster Session and Loadbalancing needs to be set up.<br />
<br />
[[OXLoadBalancingClustering_SessionLoadbalancing|Session and Loadbalancing for clustered environments]]<br />
<br />
[[OXLoadBalancingClustering_NetworkConfiguration|Network configuration for clustered environments]]<br />
<br />
You also should install and configure the OXtender for Business Mobility:<br />
<br />
[[OXtender_for_Business_Mobility| exchange active sync configuration for Open-Xchange]]<br />
<br />
Let your users connect to their data from other services like Facebook, Twitter or LinkedIn by configuring the "SocialOX"<br />
<br />
[[SocialOX|SocialOX-Configuration]]<br />
<br />
= Installation Steps depending on your environment - Instructions & Recommendations =<br />
<br />
'''The following components need to be implemented in your environment.'''<br />
<br />
<br />
== Implement Load Balancer ==<br />
<br />
A load balancer in front of the OX servers is necessary for this deployment size. It needs to handle the requests if one OX server fails.<br />
<br />
If you already have a hardware load balancing solution in place, this can be used. OX is known to work with the standard load balancing solutions from BigIP, Barracuda, Foundry, ...<br />
<br />
If you do not have a load balancing solution already in place, we recommend to use [http://www.keepalived.org/ Keepalived] as reliable and cost effective solution.<br />
<br />
Read more about configuring [[Keepalived | Keepalived for Open-Xchange]]<br />
<br />
<br />
{{OX_HE_Tutorial_CP}}<br />
<br />
<br />
{{OX_HE_Tutorial_HGP}}<br />
<br />
<br />
{{OX_HE_Tutorial_POA}}<br />
<br />
<br />
{{OX_HE_Tutorial_Auth}}<br />
<br />
== Connect Email System ==<br />
<br />
Every email system providing IMAP and SMTP can be used as backend to OX. Best experiences are made with the widespread Linux based IMAP servers [http://dovecot.org/ Dovecot], [http://www.cyrusimap.org/ Cyrus] or [http://www.courier-mta.org/imap/ Courier]. <br />
<br />
Other IMAP servers need to be tested thoroughly before going into production.<br />
<br />
There are several possibilities to implement the Email system:<br />
<br />
# You already have an email system available: Nothing needs to be done, it just needs to be configured<br />
# You use Parallels Automation (POA): Nothing special needs to be done, everything you need is contained in the APS package<br />
# You want to setup a new Email system: It is recommended to use Dovecot, as this is very stable, fast, feature rich and easy to scale<br />
<br />
<br />
{{OX_HE_Tutorial_Dovecot}}<br />
<br />
<br />
{{AppSuite:OX_Tutorial_Next}}</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Tutorial_1M&diff=16930AppSuite:OX Tutorial 1M2014-01-30T15:24:17Z<p>Dennis Sieben: /* Recommended Optional Next Steps */</p>
<hr />
<div>= Tutorial: High Available OX App Suite Setup for up to 1 Milion users =<br />
<br />
'''This article describes what you need for a typical OX App Suite Setup for up to 1.000.000 Users, which is fully clustered, high available and scaling very flexible.'''<br />
<br />
It contains everything you need to:<br />
* Understand the design of the OX App Suite setup including additional services<br />
* Install the whole system based on the relevant articles<br />
* Find pointers to the next steps of integration<br />
<br />
<br />
= System Design =<br />
<br />
[[Image:AppSuite-1M.png|1000px]]<br />
<br />
The system is designed to provide maximum functionality and availability with a minimum of necessary hardware. If the services on one OX server fail, this is transparently handled by the load balancer. If one MySQL server fails, it is sufficient to take over the IP address on the other MySQL server in the cluster to stay fully in operation.<br />
<br />
== General recommendations ==<br />
<br />
* A virtualisation enviroment is recommended<br />
* Many machines with less memory (16 GB) are preferred to fewer machines with big memory<br />
* The picture above shows a valid setup for a webmail only system. Further features like the Business Mobility Connector or OX Documentes require more ressources.<br />
<br />
== Infrastructure Components not delivered by OX ==<br />
<br />
* An email system providing IMAP and SMTP<br />
* A control panel for creation and administration of users<br />
* A Load Balancer in front of the OX servers (optional, recommended)<br />
<br />
= Overview Installation Steps =<br />
<br />
'''To deploy the described OX setup, the following steps need to be done. '''<br />
<br />
<br />
== Mandatory Steps ==<br />
# Initialize and configure MySQL database servers<br />
# Install and configure OX on all servers<br />
<br />
== Steps depending on your environment ==<br />
# Implement Load Balancer<br />
# Connect Control Panel<br />
# Connect Email System<br />
<br />
== Recommended Optional Next Steps ==<br />
# Automated Frontend Tests<br />
# Upsell Plugin (see [[AppSuite:Upsell]] and [[AppSuite:Upsell_tools]])<br />
# Mobile Autoconfiguration<br />
# Automatic FailOver<br />
# Branding<br />
<br />
= Mandatory Installation Steps - Instructions & Recommendations =<br />
<br />
<br />
'''The following steps need to be done in every case to get OX up and running:'''<br />
<br />
== Initialize and configure MySQL database on both servers ==<br />
<br />
MySQL will be configured as Master-Master configuration to ensure data consistency on both servers.<br />
If one machine fails, the other machine will take over all functionality.<br />
<br />
[[OXLoadBalancingClustering_Database|Database setup for clustered environments]]<br />
<br />
== Install and configure OX on both servers ==<br />
<br />
OX will be installed on minimum two servers. It will be configured to '''write''' to the '''first''' MySQL database and to '''read''' from the '''second''' MySQL database in one cluster. This will distribute the load during normal operation as smooth as possible. During FailOver the IP address of the failed MySQL server will be taken over to the working server, the system stays operable.<br />
<br />
[[AppSuite:OXLoadBalancingClustering_OXConfiguration|Open-Xchange setup and configuration for clustered environments]]<br />
<br />
The NFS server will be mounted on all machines and registered as filestore.<br />
<br />
[[OXLoadBalancingClustering_Filestore|Filestore setup for clustered environments]]<br />
<br />
When multiple Open-Xchange Servers are configured within a cluster Session and Loadbalancing needs to be set up.<br />
<br />
[[OXLoadBalancingClustering_SessionLoadbalancing|Session and Loadbalancing for clustered environments]]<br />
<br />
[[OXLoadBalancingClustering_NetworkConfiguration|Network configuration for clustered environments]]<br />
<br />
You also should install and configure the OXtender for Business Mobility:<br />
<br />
[[OXtender_for_Business_Mobility| exchange active sync configuration for Open-Xchange]]<br />
<br />
Let your users connect to their data from other services like Facebook, Twitter or LinkedIn by configuring the "SocialOX"<br />
<br />
[[SocialOX|SocialOX-Configuration]]<br />
<br />
= Installation Steps depending on your environment - Instructions & Recommendations =<br />
<br />
'''The following components need to be implemented in your environment.'''<br />
<br />
<br />
== Implement Load Balancer ==<br />
<br />
A load balancer in front of the OX servers is necessary for this deployment size. It needs to handle the requests if one OX server fails.<br />
<br />
If you already have a hardware load balancing solution in place, this can be used. OX is known to work with the standard load balancing solutions from BigIP, Barracuda, Foundry, ...<br />
<br />
If you do not have a load balancing solution already in place, we recommend to use [http://www.keepalived.org/ Keepalived] as reliable and cost effective solution.<br />
<br />
Read more about configuring [[Keepalived | Keepalived for Open-Xchange]]<br />
<br />
<br />
{{OX_HE_Tutorial_CP}}<br />
<br />
<br />
{{OX_HE_Tutorial_HGP}}<br />
<br />
<br />
{{OX_HE_Tutorial_POA}}<br />
<br />
<br />
{{OX_HE_Tutorial_Auth}}<br />
<br />
== Connect Email System ==<br />
<br />
Every email system providing IMAP and SMTP can be used as backend to OX. Best experiences are made with the widespread Linux based IMAP servers [http://dovecot.org/ Dovecot], [http://www.cyrusimap.org/ Cyrus] or [http://www.courier-mta.org/imap/ Courier]. <br />
<br />
Other IMAP servers need to be tested thoroughly before going into production.<br />
<br />
There are several possibilities to implement the Email system:<br />
<br />
# You already have an email system available: Nothing needs to be done, it just needs to be configured<br />
# You use Parallels Automation (POA): Nothing special needs to be done, everything you need is contained in the APS package<br />
# You want to setup a new Email system: It is recommended to use Dovecot, as this is very stable, fast, feature rich and easy to scale<br />
<br />
<br />
{{OX_HE_Tutorial_Dovecot}}<br />
<br />
<br />
{{AppSuite:OX_Tutorial_Next}}</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Tutorial_1M&diff=16929AppSuite:OX Tutorial 1M2014-01-30T15:17:06Z<p>Dennis Sieben: /* Core Components for OX App Suite */</p>
<hr />
<div>= Tutorial: High Available OX App Suite Setup for up to 1 Milion users =<br />
<br />
'''This article describes what you need for a typical OX App Suite Setup for up to 1.000.000 Users, which is fully clustered, high available and scaling very flexible.'''<br />
<br />
It contains everything you need to:<br />
* Understand the design of the OX App Suite setup including additional services<br />
* Install the whole system based on the relevant articles<br />
* Find pointers to the next steps of integration<br />
<br />
<br />
= System Design =<br />
<br />
[[Image:AppSuite-1M.png|1000px]]<br />
<br />
The system is designed to provide maximum functionality and availability with a minimum of necessary hardware. If the services on one OX server fail, this is transparently handled by the load balancer. If one MySQL server fails, it is sufficient to take over the IP address on the other MySQL server in the cluster to stay fully in operation.<br />
<br />
== General recommendations ==<br />
<br />
* A virtualisation enviroment is recommended<br />
* Many machines with less memory (16 GB) are preferred to fewer machines with big memory<br />
* The picture above shows a valid setup for a webmail only system. Further features like the Business Mobility Connector or OX Documentes require more ressources.<br />
<br />
== Infrastructure Components not delivered by OX ==<br />
<br />
* An email system providing IMAP and SMTP<br />
* A control panel for creation and administration of users<br />
* A Load Balancer in front of the OX servers (optional, recommended)<br />
<br />
= Overview Installation Steps =<br />
<br />
'''To deploy the described OX setup, the following steps need to be done. '''<br />
<br />
<br />
== Mandatory Steps ==<br />
# Initialize and configure MySQL database servers<br />
# Install and configure OX on all servers<br />
<br />
== Steps depending on your environment ==<br />
# Implement Load Balancer<br />
# Connect Control Panel<br />
# Connect Email System<br />
<br />
== Recommended Optional Next Steps ==<br />
# Automated Frontend Tests<br />
# Upsell Plugin<br />
# Mobile Autoconfiguration<br />
# Automatic FailOver<br />
# Branding<br />
<br />
<br />
= Mandatory Installation Steps - Instructions & Recommendations =<br />
<br />
<br />
'''The following steps need to be done in every case to get OX up and running:'''<br />
<br />
== Initialize and configure MySQL database on both servers ==<br />
<br />
MySQL will be configured as Master-Master configuration to ensure data consistency on both servers.<br />
If one machine fails, the other machine will take over all functionality.<br />
<br />
[[OXLoadBalancingClustering_Database|Database setup for clustered environments]]<br />
<br />
== Install and configure OX on both servers ==<br />
<br />
OX will be installed on minimum two servers. It will be configured to '''write''' to the '''first''' MySQL database and to '''read''' from the '''second''' MySQL database in one cluster. This will distribute the load during normal operation as smooth as possible. During FailOver the IP address of the failed MySQL server will be taken over to the working server, the system stays operable.<br />
<br />
[[AppSuite:OXLoadBalancingClustering_OXConfiguration|Open-Xchange setup and configuration for clustered environments]]<br />
<br />
The NFS server will be mounted on all machines and registered as filestore.<br />
<br />
[[OXLoadBalancingClustering_Filestore|Filestore setup for clustered environments]]<br />
<br />
When multiple Open-Xchange Servers are configured within a cluster Session and Loadbalancing needs to be set up.<br />
<br />
[[OXLoadBalancingClustering_SessionLoadbalancing|Session and Loadbalancing for clustered environments]]<br />
<br />
[[OXLoadBalancingClustering_NetworkConfiguration|Network configuration for clustered environments]]<br />
<br />
You also should install and configure the OXtender for Business Mobility:<br />
<br />
[[OXtender_for_Business_Mobility| exchange active sync configuration for Open-Xchange]]<br />
<br />
Let your users connect to their data from other services like Facebook, Twitter or LinkedIn by configuring the "SocialOX"<br />
<br />
[[SocialOX|SocialOX-Configuration]]<br />
<br />
= Installation Steps depending on your environment - Instructions & Recommendations =<br />
<br />
'''The following components need to be implemented in your environment.'''<br />
<br />
<br />
== Implement Load Balancer ==<br />
<br />
A load balancer in front of the OX servers is necessary for this deployment size. It needs to handle the requests if one OX server fails.<br />
<br />
If you already have a hardware load balancing solution in place, this can be used. OX is known to work with the standard load balancing solutions from BigIP, Barracuda, Foundry, ...<br />
<br />
If you do not have a load balancing solution already in place, we recommend to use [http://www.keepalived.org/ Keepalived] as reliable and cost effective solution.<br />
<br />
Read more about configuring [[Keepalived | Keepalived for Open-Xchange]]<br />
<br />
<br />
{{OX_HE_Tutorial_CP}}<br />
<br />
<br />
{{OX_HE_Tutorial_HGP}}<br />
<br />
<br />
{{OX_HE_Tutorial_POA}}<br />
<br />
<br />
{{OX_HE_Tutorial_Auth}}<br />
<br />
== Connect Email System ==<br />
<br />
Every email system providing IMAP and SMTP can be used as backend to OX. Best experiences are made with the widespread Linux based IMAP servers [http://dovecot.org/ Dovecot], [http://www.cyrusimap.org/ Cyrus] or [http://www.courier-mta.org/imap/ Courier]. <br />
<br />
Other IMAP servers need to be tested thoroughly before going into production.<br />
<br />
There are several possibilities to implement the Email system:<br />
<br />
# You already have an email system available: Nothing needs to be done, it just needs to be configured<br />
# You use Parallels Automation (POA): Nothing special needs to be done, everything you need is contained in the APS package<br />
# You want to setup a new Email system: It is recommended to use Dovecot, as this is very stable, fast, feature rich and easy to scale<br />
<br />
<br />
{{OX_HE_Tutorial_Dovecot}}<br />
<br />
<br />
{{AppSuite:OX_Tutorial_Next}}</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=File:AppSuite-10k.png&diff=16920File:AppSuite-10k.png2014-01-29T14:36:52Z<p>Dennis Sieben: Dennis Sieben uploaded a new version of &quot;File:AppSuite-10k.png&quot;</p>
<hr />
<div></div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=File:AppSuite-10k.png&diff=16919File:AppSuite-10k.png2014-01-29T14:35:58Z<p>Dennis Sieben: Dennis Sieben uploaded a new version of &quot;File:AppSuite-10k.png&quot;</p>
<hr />
<div></div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=File:AppSuite-100k.png&diff=16918File:AppSuite-100k.png2014-01-29T14:35:30Z<p>Dennis Sieben: Dennis Sieben uploaded a new version of &quot;File:AppSuite-100k.png&quot;</p>
<hr />
<div></div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=File:AppSuite-1M.png&diff=16917File:AppSuite-1M.png2014-01-29T14:33:57Z<p>Dennis Sieben: Dennis Sieben uploaded a new version of &quot;File:AppSuite-1M.png&quot;</p>
<hr />
<div></div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=File:AppSuite-1M.png&diff=16916File:AppSuite-1M.png2014-01-29T14:33:02Z<p>Dennis Sieben: Dennis Sieben uploaded a new version of &quot;File:AppSuite-1M.png&quot;</p>
<hr />
<div></div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Tutorial_1M&diff=16912AppSuite:OX Tutorial 1M2014-01-28T12:33:10Z<p>Dennis Sieben: /* System Design */</p>
<hr />
<div>= Tutorial: High Available OX App Suite Setup for up to 1 Milion users =<br />
<br />
'''This article describes what you need for a typical OX App Suite Setup for up to 1.000.000 Users, which is fully clustered, high available and scaling very flexible.'''<br />
<br />
It contains everything you need to:<br />
* Understand the design of the OX App Suite setup including additional services<br />
* Install the whole system based on the relevant articles<br />
* Find pointers to the next steps of integration<br />
<br />
<br />
= System Design =<br />
<br />
[[Image:AppSuite-1M.png|1000px]]<br />
<br />
The system is designed to provide maximum functionality and availability with a minimum of necessary hardware. If the services on one OX server fail, this is transparently handled by the load balancer. If one MySQL server fails, it is sufficient to take over the IP address on the other MySQL server in the cluster to stay fully in operation.<br />
<br />
== Core Components for OX App Suite ==<br />
<br />
* Minimum two (recommended three) OX AppSuite servers (HW recommendation: 32GB RAM / 8 cores each)<br />
* Minimum one MySQL cluster with two servers in Master-Master configuration (HW recommendation: 32GB RAM / 8 cores each)<br />
* NFS Server to store documents and files<br />
* Recommended for more than 500.000 mailboxes: one OX App Suite server dedicated for user provisioning (HW recommendation: 16GB RAM / 4 cores each)<br />
<br />
== Infrastructure Components not delivered by OX ==<br />
<br />
* An email system providing IMAP and SMTP<br />
* A control panel for creation and administration of users<br />
* A Load Balancer in front of the OX servers (optional, recommended)<br />
<br />
= Overview Installation Steps =<br />
<br />
'''To deploy the described OX setup, the following steps need to be done. '''<br />
<br />
<br />
== Mandatory Steps ==<br />
# Initialize and configure MySQL database servers<br />
# Install and configure OX on all servers<br />
<br />
== Steps depending on your environment ==<br />
# Implement Load Balancer<br />
# Connect Control Panel<br />
# Connect Email System<br />
<br />
== Recommended Optional Next Steps ==<br />
# Automated Frontend Tests<br />
# Upsell Plugin<br />
# Mobile Autoconfiguration<br />
# Automatic FailOver<br />
# Branding<br />
<br />
<br />
= Mandatory Installation Steps - Instructions & Recommendations =<br />
<br />
<br />
'''The following steps need to be done in every case to get OX up and running:'''<br />
<br />
== Initialize and configure MySQL database on both servers ==<br />
<br />
MySQL will be configured as Master-Master configuration to ensure data consistency on both servers.<br />
If one machine fails, the other machine will take over all functionality.<br />
<br />
[[OXLoadBalancingClustering_Database|Database setup for clustered environments]]<br />
<br />
== Install and configure OX on both servers ==<br />
<br />
OX will be installed on minimum two servers. It will be configured to '''write''' to the '''first''' MySQL database and to '''read''' from the '''second''' MySQL database in one cluster. This will distribute the load during normal operation as smooth as possible. During FailOver the IP address of the failed MySQL server will be taken over to the working server, the system stays operable.<br />
<br />
[[AppSuite:OXLoadBalancingClustering_OXConfiguration|Open-Xchange setup and configuration for clustered environments]]<br />
<br />
The NFS server will be mounted on all machines and registered as filestore.<br />
<br />
[[OXLoadBalancingClustering_Filestore|Filestore setup for clustered environments]]<br />
<br />
When multiple Open-Xchange Servers are configured within a cluster Session and Loadbalancing needs to be set up.<br />
<br />
[[OXLoadBalancingClustering_SessionLoadbalancing|Session and Loadbalancing for clustered environments]]<br />
<br />
[[OXLoadBalancingClustering_NetworkConfiguration|Network configuration for clustered environments]]<br />
<br />
You also should install and configure the OXtender for Business Mobility:<br />
<br />
[[OXtender_for_Business_Mobility| exchange active sync configuration for Open-Xchange]]<br />
<br />
Let your users connect to their data from other services like Facebook, Twitter or LinkedIn by configuring the "SocialOX"<br />
<br />
[[SocialOX|SocialOX-Configuration]]<br />
<br />
= Installation Steps depending on your environment - Instructions & Recommendations =<br />
<br />
'''The following components need to be implemented in your environment.'''<br />
<br />
<br />
== Implement Load Balancer ==<br />
<br />
A load balancer in front of the OX servers is necessary for this deployment size. It needs to handle the requests if one OX server fails.<br />
<br />
If you already have a hardware load balancing solution in place, this can be used. OX is known to work with the standard load balancing solutions from BigIP, Barracuda, Foundry, ...<br />
<br />
If you do not have a load balancing solution already in place, we recommend to use [http://www.keepalived.org/ Keepalived] as reliable and cost effective solution.<br />
<br />
Read more about configuring [[Keepalived | Keepalived for Open-Xchange]]<br />
<br />
<br />
{{OX_HE_Tutorial_CP}}<br />
<br />
<br />
{{OX_HE_Tutorial_HGP}}<br />
<br />
<br />
{{OX_HE_Tutorial_POA}}<br />
<br />
<br />
{{OX_HE_Tutorial_Auth}}<br />
<br />
== Connect Email System ==<br />
<br />
Every email system providing IMAP and SMTP can be used as backend to OX. Best experiences are made with the widespread Linux based IMAP servers [http://dovecot.org/ Dovecot], [http://www.cyrusimap.org/ Cyrus] or [http://www.courier-mta.org/imap/ Courier]. <br />
<br />
Other IMAP servers need to be tested thoroughly before going into production.<br />
<br />
There are several possibilities to implement the Email system:<br />
<br />
# You already have an email system available: Nothing needs to be done, it just needs to be configured<br />
# You use Parallels Automation (POA): Nothing special needs to be done, everything you need is contained in the APS package<br />
# You want to setup a new Email system: It is recommended to use Dovecot, as this is very stable, fast, feature rich and easy to scale<br />
<br />
<br />
{{OX_HE_Tutorial_Dovecot}}<br />
<br />
<br />
{{AppSuite:OX_Tutorial_Next}}</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=File:AppSuite-1M.png&diff=16911File:AppSuite-1M.png2014-01-28T12:32:10Z<p>Dennis Sieben: </p>
<hr />
<div></div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Tutorial_100K&diff=16910AppSuite:OX Tutorial 100K2014-01-28T12:31:25Z<p>Dennis Sieben: /* System Design */</p>
<hr />
<div>= Tutorial: High Available OX AppSuite Setup for up to 100.000 users =<br />
<br />
'''This article describes what you need for a typical OX AppSuite Setup for up to 100.000 Users, which is fully clustered and high available.'''<br />
<br />
It contains everything you need to:<br />
* Understand the design of the OX AppSuite setup including additional services<br />
* Install the whole system based on the relevant articles<br />
* Find pointers to the next steps of integration<br />
<br />
<br />
= System Design =<br />
<br />
[[Image:AppSuite-100k.png|800px]]<br />
<br />
The system is designed to provide maximum functionality and availability with a minimum of necessary hardware. If the services on one server fail, it is enough to take over the IP address to the other machine and service will stay up and running.<br />
<br />
== Core Components for OX AppSuite ==<br />
<br />
* Two OX AppSuite servers (HW recommendation: 16GB RAM / 4 cores each)<br />
* MySQL installed directly on these server <br />
* NFS Server to store documents and files<br />
<br />
== Infrastructure Components not delivered by OX ==<br />
<br />
* An email system providing IMAP and SMTP<br />
* A control panel for creation and administration of users<br />
* A Load Balancer in front of the OX servers (optional, recommended)<br />
<br />
= Overview Installation Steps =<br />
<br />
'''To deploy the described OX setup, the following steps need to be done. '''<br />
<br />
<br />
== Mandatory Steps ==<br />
# Initialize and configure MySQL database on both servers<br />
# Install and configure OX on both servers<br />
<br />
== Steps depending on your environment ==<br />
# Implement Load Balancer<br />
# Connect Control Panel<br />
# Connect Email System<br />
<br />
== Recommended Optional Next Steps ==<br />
# Automated Frontend Tests<br />
# Upsell Plugin<br />
# Mobile Autoconfiguration<br />
# Automatic FailOver<br />
# Branding<br />
<br />
<br />
= Mandatory Installation Steps - Instructions & Recommendations =<br />
<br />
<br />
'''The following steps need to be done in every case to get OX up and running:'''<br />
<br />
== Initialize and configure MySQL database on both servers ==<br />
<br />
MySQL will run on both servers. MySQL will be configured as Master-Master configuration to ensure data consistency on both servers.<br />
If one machine fails, the other machine will take over all functionality.<br />
<br />
[[OXLoadBalancingClustering_Database|Database setup for clustered environments]]<br />
<br />
== Install and configure OX on both servers ==<br />
<br />
OX will be installed on both servers. It will be configured to '''write''' to the '''first''' MySQL database and to '''read''' from the '''second''' MySQL database. This will distribute the load during normal operation as smooth as possible. During FailOver the IP address of the failed server will be taken over to the working server, the system stays operable.<br />
<br />
[[AppSuite:OXLoadBalancingClustering_OXConfiguration|Open-Xchange setup and configuration for clustered environments]]<br />
<br />
The NFS server will be mounted on both machines and registered as filestore.<br />
<br />
[[OXLoadBalancingClustering_Filestore|Filestore setup for clustered environments]]<br />
<br />
When multiple Open-Xchange Servers are configured within a cluster Session and Loadbalancing needs to be set up.<br />
<br />
[[OXLoadBalancingClustering_SessionLoadbalancing|Session and Loadbalancing for clustered environments]]<br />
<br />
[[OXLoadBalancingClustering_NetworkConfiguration|Network configuration for clustered environments]]<br />
<br />
You also should install and configure the OXtender for Business Mobility<br />
<br />
[[OXtender_for_Business_Mobility_Installation_Guide|Installation of the OXtender for Business Mobility]]<br />
<br />
Let your users connect to their data from other services like Facebook, Twitter or LinkedIn by configuring the "SocialOX"<br />
<br />
[[SocialOX|SocialOX-Configuration]]<br />
<br />
= Installation Steps depending on your environment - Instructions & Recommendations =<br />
<br />
'''The following components need to be implemented in your environment.'''<br />
<br />
<br />
== Implement Load Balancer ==<br />
<br />
A load balancer in front of the OX servers is recommended, but optional in this deployment size. (In small environments, DNS Round Robin may be sufficient).<br />
<br />
If you already have a hardware load balancing solution in place, this can be used. OX is known to work with the standard load balancing solutions from BigIP, Barracuda, Foundry, ...<br />
<br />
If you do not have a load balancing solution already in place, we recommend to use [http://www.keepalived.org/ Keepalived] as reliable and cost effective solution.<br />
<br />
Read more about configuring [[Keepalived | Keepalived for Open-Xchange]]<br />
<br />
<br />
{{OX_HE_Tutorial_CP}}<br />
<br />
<br />
{{OX_HE_Tutorial_HGP}}<br />
<br />
<br />
{{OX_HE_Tutorial_POA}}<br />
<br />
<br />
{{OX_HE_Tutorial_Auth}}<br />
<br />
<br />
== Connect Email System ==<br />
<br />
Every email system providing IMAP and SMTP can be used as backend to OX. Best experiences are made with the widespread Linux based IMAP servers [http://dovecot.org/ Dovecot], [http://www.cyrusimap.org/ Cyrus] or [http://www.courier-mta.org/imap/ Courier]. <br />
<br />
Other IMAP servers need to be tested thoroughly before going into production.<br />
<br />
There are several possibilities to implement the Email system:<br />
<br />
# You already have an email system available: Nothing needs to be done, it just needs to be configured<br />
# You use Parallels Automation (POA): Nothing special needs to be done, everything you need is contained in the APS package<br />
# You want to setup a new Email system: It is recommended to use Dovecot, as this is very stable, fast, feature rich and easy to scale<br />
<br />
<br />
{{OX_HE_Tutorial_Dovecot}}<br />
<br />
<br />
{{AppSuite:OX_Tutorial_Next}}<br />
<br />
<br />
{{OX_HE_Tutorial_FailOver}}</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=File:AppSuite-100k.png&diff=16909File:AppSuite-100k.png2014-01-28T12:30:56Z<p>Dennis Sieben: </p>
<hr />
<div></div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Tutorial_10K&diff=16908AppSuite:OX Tutorial 10K2014-01-28T12:28:54Z<p>Dennis Sieben: /* System Design */</p>
<hr />
<div>= Tutorial: OX AppSuite Setup for up to 10.000 users =<br />
<br />
'''This article describes what you need for a typical OX AppSuite Setup for up to 10.000 Users with minimal efforts.'''<br />
<br />
It contains everything you need to:<br />
* Understand the design of the OX AppSuite setup including additional services<br />
* Install the whole system based on the relevant articles<br />
* Find pointers to the next steps of integration<br />
<br />
<br />
= System Design =<br />
<br />
[[Image:AppSuite-10k.png|frameless|alt=Architecture-10k|800px]]<br />
<br />
The system is designed to provide maximum functionality with a minimum of necessary hardware. All OX services are running on one single machine.<br />
<br />
<br />
== Core Components for OX AppSuite ==<br />
<br />
* One OX AppSuite server (HW recommendation: 16GB RAM / 4 cores)<br />
* MySQL installed directly on this server <br />
* Optional: NFS Server to store documents and files<br />
<br />
<br />
== Infrastructure Components not delivered by OX ==<br />
<br />
* An email system providing IMAP and SMTP<br />
* A control panel for creation and administration of users<br />
<br />
= Overview Installation Steps =<br />
<br />
'''To deploy the described OX setup, the following steps need to be done. '''<br />
<br />
<br />
== Mandatory Steps ==<br />
# Initialize and configure MySQL database<br />
# Install and configure OX service<br />
<br />
== Steps depending on your environment ==<br />
# Connect Control Panel<br />
# Connect Email System<br />
<br />
== Recommended Optional Next Steps ==<br />
# Automated Frontend Tests<br />
# Upsell Plugin<br />
# Mobile Autoconfiguration<br />
# Branding<br />
<br />
<br />
= Mandatory Installation Steps - Instructions & Recommendations =<br />
<br />
<br />
'''The following steps need to be done in every case to get OX up and running:'''<br />
<br />
== Install and configure OX ==<br />
<br />
OX will be installed on the server.<br />
<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_6.0|Download and Installation Guide for Debian GNU/Linux 6.0 (Squeeze)]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_7.0|Download and Installation Guide for Debian GNU/Linux 7.0 (Wheezy)]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_SLES11|Download and Installation Guide for SUSE Linux Enterprise Server 11]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_RHEL6|Download and Installation Guide for RedHat Enterprise Linux 6]]<br />
<br />
You also should install and configure the OXtender for Business Mobility<br />
<br />
[[AppSuite:OXtender_for_Business_Mobility_Installation_Guide|Installation of the OXtender for Business Mobility]]<br />
<br />
Let your users connect to their data from other services like Facebook, Twitter or LinkedIn by configuring the "SocialOX"<br />
<br />
[[SocialOX|SocialOX-Configuration]]<br />
<br />
= Installation Steps depending on your environment - Instructions & Recommendations =<br />
<br />
'''The following components need to be implemented in your environment.'''<br />
<br />
<br />
{{OX_HE_Tutorial_CP}}<br />
<br />
<br />
{{OX_HE_Tutorial_HGP}}<br />
<br />
<br />
{{OX_HE_Tutorial_Plesk}}<br />
<br />
<br />
{{OX_HE_Tutorial_Auth}}<br />
<br />
<br />
== Connect Email System ==<br />
<br />
Every email system providing IMAP and SMTP can be used as backend to OX. Best experiences are made with the widespread Linux based IMAP servers [http://dovecot.org/ Dovecot], [http://www.cyrusimap.org/ Cyrus] or [http://www.courier-mta.org/imap/ Courier]. <br />
<br />
Other IMAP servers need to be tested thoroughly before going into production.<br />
<br />
There are several possibilities to implement the Email system:<br />
<br />
# You already have an email system available: Nothing needs to be done, it just needs to be configured<br />
# You use Plesk Panel: Nothing special needs to be done, everything you need is contained in the OXtender for Plesk<br />
# You want to setup a new Email system: It is recommended to use Dovecot, as this is very stable, fast, feature rich and easy to scale<br />
<br />
<br />
{{OX_HE_Tutorial_Dovecot}}<br />
<br />
<br />
{{AppSuite:OX_Tutorial_Next}}</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Tutorial_10K&diff=16907AppSuite:OX Tutorial 10K2014-01-28T12:23:19Z<p>Dennis Sieben: /* System Design */</p>
<hr />
<div>= Tutorial: OX AppSuite Setup for up to 10.000 users =<br />
<br />
'''This article describes what you need for a typical OX AppSuite Setup for up to 10.000 Users with minimal efforts.'''<br />
<br />
It contains everything you need to:<br />
* Understand the design of the OX AppSuite setup including additional services<br />
* Install the whole system based on the relevant articles<br />
* Find pointers to the next steps of integration<br />
<br />
<br />
= System Design =<br />
<br />
[[Image:AppSuite-10k.png]]<br />
<br />
The system is designed to provide maximum functionality with a minimum of necessary hardware. All OX services are running on one single machine.<br />
<br />
<br />
== Core Components for OX AppSuite ==<br />
<br />
* One OX AppSuite server (HW recommendation: 16GB RAM / 4 cores)<br />
* MySQL installed directly on this server <br />
* Optional: NFS Server to store documents and files<br />
<br />
<br />
== Infrastructure Components not delivered by OX ==<br />
<br />
* An email system providing IMAP and SMTP<br />
* A control panel for creation and administration of users<br />
<br />
= Overview Installation Steps =<br />
<br />
'''To deploy the described OX setup, the following steps need to be done. '''<br />
<br />
<br />
== Mandatory Steps ==<br />
# Initialize and configure MySQL database<br />
# Install and configure OX service<br />
<br />
== Steps depending on your environment ==<br />
# Connect Control Panel<br />
# Connect Email System<br />
<br />
== Recommended Optional Next Steps ==<br />
# Automated Frontend Tests<br />
# Upsell Plugin<br />
# Mobile Autoconfiguration<br />
# Branding<br />
<br />
<br />
= Mandatory Installation Steps - Instructions & Recommendations =<br />
<br />
<br />
'''The following steps need to be done in every case to get OX up and running:'''<br />
<br />
== Install and configure OX ==<br />
<br />
OX will be installed on the server.<br />
<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_6.0|Download and Installation Guide for Debian GNU/Linux 6.0 (Squeeze)]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_7.0|Download and Installation Guide for Debian GNU/Linux 7.0 (Wheezy)]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_SLES11|Download and Installation Guide for SUSE Linux Enterprise Server 11]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_RHEL6|Download and Installation Guide for RedHat Enterprise Linux 6]]<br />
<br />
You also should install and configure the OXtender for Business Mobility<br />
<br />
[[AppSuite:OXtender_for_Business_Mobility_Installation_Guide|Installation of the OXtender for Business Mobility]]<br />
<br />
Let your users connect to their data from other services like Facebook, Twitter or LinkedIn by configuring the "SocialOX"<br />
<br />
[[SocialOX|SocialOX-Configuration]]<br />
<br />
= Installation Steps depending on your environment - Instructions & Recommendations =<br />
<br />
'''The following components need to be implemented in your environment.'''<br />
<br />
<br />
{{OX_HE_Tutorial_CP}}<br />
<br />
<br />
{{OX_HE_Tutorial_HGP}}<br />
<br />
<br />
{{OX_HE_Tutorial_Plesk}}<br />
<br />
<br />
{{OX_HE_Tutorial_Auth}}<br />
<br />
<br />
== Connect Email System ==<br />
<br />
Every email system providing IMAP and SMTP can be used as backend to OX. Best experiences are made with the widespread Linux based IMAP servers [http://dovecot.org/ Dovecot], [http://www.cyrusimap.org/ Cyrus] or [http://www.courier-mta.org/imap/ Courier]. <br />
<br />
Other IMAP servers need to be tested thoroughly before going into production.<br />
<br />
There are several possibilities to implement the Email system:<br />
<br />
# You already have an email system available: Nothing needs to be done, it just needs to be configured<br />
# You use Plesk Panel: Nothing special needs to be done, everything you need is contained in the OXtender for Plesk<br />
# You want to setup a new Email system: It is recommended to use Dovecot, as this is very stable, fast, feature rich and easy to scale<br />
<br />
<br />
{{OX_HE_Tutorial_Dovecot}}<br />
<br />
<br />
{{AppSuite:OX_Tutorial_Next}}</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=File:AppSuite-10k.png&diff=16906File:AppSuite-10k.png2014-01-28T12:22:55Z<p>Dennis Sieben: </p>
<hr />
<div></div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Tutorial_10K&diff=16904AppSuite:OX Tutorial 10K2014-01-28T09:11:24Z<p>Dennis Sieben: /* System Design */</p>
<hr />
<div>= Tutorial: OX AppSuite Setup for up to 10.000 users =<br />
<br />
'''This article describes what you need for a typical OX AppSuite Setup for up to 10.000 Users with minimal efforts.'''<br />
<br />
It contains everything you need to:<br />
* Understand the design of the OX AppSuite setup including additional services<br />
* Install the whole system based on the relevant articles<br />
* Find pointers to the next steps of integration<br />
<br />
<br />
= System Design =<br />
<br />
[[Image:SaaS-10k.svg]]<br />
<br />
The system is designed to provide maximum functionality with a minimum of necessary hardware. All OX services are running on one single machine.<br />
<br />
<br />
== Core Components for OX AppSuite ==<br />
<br />
* One OX AppSuite server (HW recommendation: 16GB RAM / 4 cores)<br />
* MySQL installed directly on this server <br />
* Optional: NFS Server to store documents and files<br />
<br />
<br />
== Infrastructure Components not delivered by OX ==<br />
<br />
* An email system providing IMAP and SMTP<br />
* A control panel for creation and administration of users<br />
<br />
= Overview Installation Steps =<br />
<br />
'''To deploy the described OX setup, the following steps need to be done. '''<br />
<br />
<br />
== Mandatory Steps ==<br />
# Initialize and configure MySQL database<br />
# Install and configure OX service<br />
<br />
== Steps depending on your environment ==<br />
# Connect Control Panel<br />
# Connect Email System<br />
<br />
== Recommended Optional Next Steps ==<br />
# Automated Frontend Tests<br />
# Upsell Plugin<br />
# Mobile Autoconfiguration<br />
# Branding<br />
<br />
<br />
= Mandatory Installation Steps - Instructions & Recommendations =<br />
<br />
<br />
'''The following steps need to be done in every case to get OX up and running:'''<br />
<br />
== Install and configure OX ==<br />
<br />
OX will be installed on the server.<br />
<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_6.0|Download and Installation Guide for Debian GNU/Linux 6.0 (Squeeze)]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_7.0|Download and Installation Guide for Debian GNU/Linux 7.0 (Wheezy)]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_SLES11|Download and Installation Guide for SUSE Linux Enterprise Server 11]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_RHEL6|Download and Installation Guide for RedHat Enterprise Linux 6]]<br />
<br />
You also should install and configure the OXtender for Business Mobility<br />
<br />
[[AppSuite:OXtender_for_Business_Mobility_Installation_Guide|Installation of the OXtender for Business Mobility]]<br />
<br />
Let your users connect to their data from other services like Facebook, Twitter or LinkedIn by configuring the "SocialOX"<br />
<br />
[[SocialOX|SocialOX-Configuration]]<br />
<br />
= Installation Steps depending on your environment - Instructions & Recommendations =<br />
<br />
'''The following components need to be implemented in your environment.'''<br />
<br />
<br />
{{OX_HE_Tutorial_CP}}<br />
<br />
<br />
{{OX_HE_Tutorial_HGP}}<br />
<br />
<br />
{{OX_HE_Tutorial_Plesk}}<br />
<br />
<br />
{{OX_HE_Tutorial_Auth}}<br />
<br />
<br />
== Connect Email System ==<br />
<br />
Every email system providing IMAP and SMTP can be used as backend to OX. Best experiences are made with the widespread Linux based IMAP servers [http://dovecot.org/ Dovecot], [http://www.cyrusimap.org/ Cyrus] or [http://www.courier-mta.org/imap/ Courier]. <br />
<br />
Other IMAP servers need to be tested thoroughly before going into production.<br />
<br />
There are several possibilities to implement the Email system:<br />
<br />
# You already have an email system available: Nothing needs to be done, it just needs to be configured<br />
# You use Plesk Panel: Nothing special needs to be done, everything you need is contained in the OXtender for Plesk<br />
# You want to setup a new Email system: It is recommended to use Dovecot, as this is very stable, fast, feature rich and easy to scale<br />
<br />
<br />
{{OX_HE_Tutorial_Dovecot}}<br />
<br />
<br />
{{AppSuite:OX_Tutorial_Next}}</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=File:SaaS-10k.svg&diff=16903File:SaaS-10k.svg2014-01-28T09:09:39Z<p>Dennis Sieben: </p>
<hr />
<div></div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=Caldav_carddav_Bundles&diff=16634Caldav carddav Bundles2013-12-03T14:31:14Z<p>Dennis Sieben: /* Alternative 2: Apache useragent detection */</p>
<hr />
<div>= Installation and Configuration of the CalDAV- and CardDAV-bundles =<br />
<br />
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.<br />
<br />
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. <br />
<br />
== User Guide and Client Configuration ==<br />
Please find further information regarding the client configuration at [[CalDAVClients]] and [[CardDAVClients]].<br />
<br />
== Webserver Configuration ==<br />
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. Please be aware that for a working Mavericks auto configuration setup you need to have SSL enabled on the server. The non-SSL variant described below only works if you use the advanced CalDav configuration in Mavericks and enter the path by hand. If you just want to enter the hostname SSL is required. The same applies to iOS7 where SSL is always required.<br />
<br />
=== Alternative 1: Apache vhost (recommended) ===<br />
Please edit your site configuration file for OX so that ''' the existing OX configuration as well as the CalDAV/CardDav configuration are placed inside their own virtual hosts sections.'''.<br />
<br />
Please add the following entries before you existing VirtualHost entry. This is an <b>example</b> where MYSERVER.TLD is the domain-name of the ox-server:<br />
<br />
NameVirtualHost *:80<br />
<VirtualHost *:80><br />
ServerName dav.<MYSERVER.TLD><br />
ErrorLog /tmp/dav.err.log<br />
TransferLog /tmp/dav.access.log<br />
<br />
<Proxy balancer://oxserver-sync><br />
Order deny,allow<br />
Allow from all<br />
<br />
# for ajp http service<br />
BalancerMember ajp://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1<br />
# for grizzly http service<br />
#BalancerMember http://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1<br />
# uncomment this entry if you have a clustered setup and want to use the other nodes too<br />
#BalancerMember http://<ip-of-other-host>:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
<Proxy /><br />
Order allow,deny<br />
Allow from all<br />
ProxyPass balancer://oxserver-sync/servlet/dav/<br />
</Proxy><br />
</VirtualHost><br />
<br />
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.<br />
<br />
Please note the <code>NameVirtualHost</code> directive is needed to be able to specify multiple virtual hosts for the same IP. The differentiation is only done by the given <code>ServerName</code>. This implies that you need two server names, so the virtual host entry for the existing ox site configuration needs to be also enriched by a <code>ServerName</code> if not already present. If you access the system without one of the given <code>ServerName</code>s so e.g. via the IP the system will pick the corresponding one by order (in this case the DAV part first. If you want it to work differently please change the order accordingly.<br />
<br />
=== Alternative 2: Apache useragent detection ===<br />
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.<br />
<br />
$ vi <your-ox-site-configuration-file><br />
<br />
RewriteEngine On<br />
RewriteCond %{HTTP_USER_AGENT} Calendar [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DataAccess [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DAVKit [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Lightning [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adresboek [OR]<br />
RewriteCond %{HTTP_USER_AGENT} dataaccessd [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Preferences [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adressbuch [OR]<br />
RewriteCond %{HTTP_USER_AGENT} AddressBook [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Address%20Book [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CalendarStore [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CoreDAV<br />
# select if you run ajp (proxy_ajp.conf) or grizzly (proxy_http.conf), here ajp is used:<br />
RewriteRule (.*) ajp://localhost:8009/servlet/dav$1 [P] # for ajp http service<br />
#RewriteRule (.*) http://localhost:8009/servlet/dav$1 [P] # for grizzly http service<br />
<br />
'''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.<br />
<br />
== Autodiscovery ==<br />
<br />
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]. <br />
<br />
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:<br />
<br />
_caldavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.<br />
_caldav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.<br />
_carddavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.<br />
_carddav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.<br />
<br />
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:<br />
<br />
RewriteEngine On<br />
RewriteCond %{REQUEST_URI} ^/\.well-known/caldav [OR]<br />
RewriteCond %{REQUEST_URI} ^/\.well-known/carddav<br />
RewriteRule (.*) / [L,R]<br />
<br />
== Which packages do I need? ==<br />
To get CalDAV and CardDAV up and running you need the following packages:<br />
<br />
In v6.20 and earlier:<br />
* 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.<br />
* 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.<br />
* open-xchange-carddav - The CardDAV interface exposing the users addressbook via carddav<br />
* open-xchange-caldav - The CalDAV inteface exposing the users calendars via caldav<br />
<br />
<br />
With v6.22 we have significantly reduced the number of packages necessary to install Open-Xchange Server.<br />
In v6.22 and later only one package is needed:<br />
* open-xchange-dav <br />
<br />
== Installation on OX App Suite ==<br />
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<br />
<br />
<br />
{{InstallPlugin|pluginname=open-xchange-caldav open-xchange-carddav open-xchange-webdav-acl open-xchange-webdav-directory |sopath=updates}}<br />
<br />
{{InstallPlugin|pluginname=open-xchange-dav|sopath=6.22/updates/backend|version=v6.22.x}}<br />
<br />
<br />
== CalDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files caldav.properties and caldav.yml:<br />
<br />
===com.openexchange.caldav.enabled===<br />
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:<br />
<br />
In v6.20 and earlier:<br />
<br />
/opt/open-xchange/etc/groupware/caldav.properties:<br />
com.openexchange.caldav.enabled=false<br />
<br />
/opt/open-xchange/etc/groupware/contextSets/caldav.yml<br />
premium:<br />
com.openexchange.caldav.enabled: true<br />
withTags: ucInfostore<br />
<br />
With v6.22 and up:<br />
<br />
/opt/open-xchange/etc/caldav.properties:<br />
com.openexchange.caldav.enabled=false<br />
<br />
/opt/open-xchange/etc/contextSets/caldav.yml<br />
premium:<br />
com.openexchange.caldav.enabled: true<br />
withTags: ucInfostore<br />
<br />
<br />
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.<br />
<br />
===com.openexchange.caldav.tree===<br />
Configures the ID of the folder tree used by the CalDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.caldav.interval.start===<br />
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". <br />
<br />
===com.openexchange.caldav.interval.end===<br />
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". <br />
<br />
===com.openexchange.caldav.url===<br />
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].<br />
<br />
<br />
== CardDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files carddav.properties and carddav.yml:<br />
<br />
===com.openexchange.carddav.enabled===<br />
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:<br />
<br />
/opt/open-xchange/etc/groupware/carddav.properties:<br />
com.openexchange.carddav.enabled=false<br />
<br />
/opt/open-xchange/etc/groupware/contextSets/carddav.yml<br />
premium:<br />
com.openexchange.carddav.enabled: true<br />
withTags: ucInfostore<br />
<br />
===com.openexchange.carddav.ignoreFolders===<br />
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.<br />
<br />
===com.openexchange.carddav.tree===<br />
Configures the ID of the folder tree used by the CardDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.carddav.exposedCollections===<br />
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'. <br />
<br />
===com.openexchange.carddav.userAgentForAggregatedCollection===<br />
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. <br />
<br />
===com.openexchange.carddav.reducedAggregatedCollection===<br />
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.<br />
<br />
[[Category: Clients]]<br />
[[Category: Administrator]]<br />
[[Category: AppSuite]]</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=Caldav_carddav_Bundles&diff=16633Caldav carddav Bundles2013-12-03T14:13:05Z<p>Dennis Sieben: /* Alternative 1: Apache vhost (recommended) */</p>
<hr />
<div>= Installation and Configuration of the CalDAV- and CardDAV-bundles =<br />
<br />
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.<br />
<br />
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. <br />
<br />
== User Guide and Client Configuration ==<br />
Please find further information regarding the client configuration at [[CalDAVClients]] and [[CardDAVClients]].<br />
<br />
== Webserver Configuration ==<br />
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. Please be aware that for a working Mavericks auto configuration setup you need to have SSL enabled on the server. The non-SSL variant described below only works if you use the advanced CalDav configuration in Mavericks and enter the path by hand. If you just want to enter the hostname SSL is required. The same applies to iOS7 where SSL is always required.<br />
<br />
=== Alternative 1: Apache vhost (recommended) ===<br />
Please edit your site configuration file for OX so that ''' the existing OX configuration as well as the CalDAV/CardDav configuration are placed inside their own virtual hosts sections.'''.<br />
<br />
Please add the following entries before you existing VirtualHost entry. This is an <b>example</b> where MYSERVER.TLD is the domain-name of the ox-server:<br />
<br />
NameVirtualHost *:80<br />
<VirtualHost *:80><br />
ServerName dav.<MYSERVER.TLD><br />
ErrorLog /tmp/dav.err.log<br />
TransferLog /tmp/dav.access.log<br />
<br />
<Proxy balancer://oxserver-sync><br />
Order deny,allow<br />
Allow from all<br />
<br />
# for ajp http service<br />
BalancerMember ajp://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1<br />
# for grizzly http service<br />
#BalancerMember http://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1<br />
# uncomment this entry if you have a clustered setup and want to use the other nodes too<br />
#BalancerMember http://<ip-of-other-host>:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
<Proxy /><br />
Order allow,deny<br />
Allow from all<br />
ProxyPass balancer://oxserver-sync/servlet/dav/<br />
</Proxy><br />
</VirtualHost><br />
<br />
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.<br />
<br />
Please note the <code>NameVirtualHost</code> directive is needed to be able to specify multiple virtual hosts for the same IP. The differentiation is only done by the given <code>ServerName</code>. This implies that you need two server names, so the virtual host entry for the existing ox site configuration needs to be also enriched by a <code>ServerName</code> if not already present. If you access the system without one of the given <code>ServerName</code>s so e.g. via the IP the system will pick the corresponding one by order (in this case the DAV part first. If you want it to work differently please change the order accordingly.<br />
<br />
=== Alternative 2: Apache useragent detection ===<br />
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.<br />
<br />
$ vi /etc/apache2/ox6.conf<br />
<br />
RewriteEngine On<br />
RewriteCond %{HTTP_USER_AGENT} Calendar [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DataAccess [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DAVKit [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Lightning [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adresboek [OR]<br />
RewriteCond %{HTTP_USER_AGENT} dataaccessd [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Preferences [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adressbuch [OR]<br />
RewriteCond %{HTTP_USER_AGENT} AddressBook [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Address%20Book [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CalendarStore [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CoreDAV<br />
# select if you run ajp (proxy_ajp.conf) or grizzly (proxy_http.conf), here ajp is used:<br />
RewriteRule (.*) ajp://localhost:8009/servlet/dav$1 [P] # for ajp http service<br />
#RewriteRule (.*) http://localhost:8009/servlet/dav$1 [P] # for grizzly http service<br />
<br />
'''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.<br />
<br />
== Autodiscovery ==<br />
<br />
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]. <br />
<br />
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:<br />
<br />
_caldavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.<br />
_caldav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.<br />
_carddavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.<br />
_carddav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.<br />
<br />
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:<br />
<br />
RewriteEngine On<br />
RewriteCond %{REQUEST_URI} ^/\.well-known/caldav [OR]<br />
RewriteCond %{REQUEST_URI} ^/\.well-known/carddav<br />
RewriteRule (.*) / [L,R]<br />
<br />
== Which packages do I need? ==<br />
To get CalDAV and CardDAV up and running you need the following packages:<br />
<br />
In v6.20 and earlier:<br />
* 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.<br />
* 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.<br />
* open-xchange-carddav - The CardDAV interface exposing the users addressbook via carddav<br />
* open-xchange-caldav - The CalDAV inteface exposing the users calendars via caldav<br />
<br />
<br />
With v6.22 we have significantly reduced the number of packages necessary to install Open-Xchange Server.<br />
In v6.22 and later only one package is needed:<br />
* open-xchange-dav <br />
<br />
== Installation on OX App Suite ==<br />
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<br />
<br />
<br />
{{InstallPlugin|pluginname=open-xchange-caldav open-xchange-carddav open-xchange-webdav-acl open-xchange-webdav-directory |sopath=updates}}<br />
<br />
{{InstallPlugin|pluginname=open-xchange-dav|sopath=6.22/updates/backend|version=v6.22.x}}<br />
<br />
<br />
== CalDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files caldav.properties and caldav.yml:<br />
<br />
===com.openexchange.caldav.enabled===<br />
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:<br />
<br />
In v6.20 and earlier:<br />
<br />
/opt/open-xchange/etc/groupware/caldav.properties:<br />
com.openexchange.caldav.enabled=false<br />
<br />
/opt/open-xchange/etc/groupware/contextSets/caldav.yml<br />
premium:<br />
com.openexchange.caldav.enabled: true<br />
withTags: ucInfostore<br />
<br />
With v6.22 and up:<br />
<br />
/opt/open-xchange/etc/caldav.properties:<br />
com.openexchange.caldav.enabled=false<br />
<br />
/opt/open-xchange/etc/contextSets/caldav.yml<br />
premium:<br />
com.openexchange.caldav.enabled: true<br />
withTags: ucInfostore<br />
<br />
<br />
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.<br />
<br />
===com.openexchange.caldav.tree===<br />
Configures the ID of the folder tree used by the CalDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.caldav.interval.start===<br />
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". <br />
<br />
===com.openexchange.caldav.interval.end===<br />
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". <br />
<br />
===com.openexchange.caldav.url===<br />
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].<br />
<br />
<br />
== CardDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files carddav.properties and carddav.yml:<br />
<br />
===com.openexchange.carddav.enabled===<br />
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:<br />
<br />
/opt/open-xchange/etc/groupware/carddav.properties:<br />
com.openexchange.carddav.enabled=false<br />
<br />
/opt/open-xchange/etc/groupware/contextSets/carddav.yml<br />
premium:<br />
com.openexchange.carddav.enabled: true<br />
withTags: ucInfostore<br />
<br />
===com.openexchange.carddav.ignoreFolders===<br />
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.<br />
<br />
===com.openexchange.carddav.tree===<br />
Configures the ID of the folder tree used by the CardDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.carddav.exposedCollections===<br />
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'. <br />
<br />
===com.openexchange.carddav.userAgentForAggregatedCollection===<br />
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. <br />
<br />
===com.openexchange.carddav.reducedAggregatedCollection===<br />
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.<br />
<br />
[[Category: Clients]]<br />
[[Category: Administrator]]<br />
[[Category: AppSuite]]</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=Caldav_carddav_Bundles&diff=16632Caldav carddav Bundles2013-12-03T13:37:03Z<p>Dennis Sieben: /* Webserver Configuration */</p>
<hr />
<div>= Installation and Configuration of the CalDAV- and CardDAV-bundles =<br />
<br />
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.<br />
<br />
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. <br />
<br />
== User Guide and Client Configuration ==<br />
Please find further information regarding the client configuration at [[CalDAVClients]] and [[CardDAVClients]].<br />
<br />
== Webserver Configuration ==<br />
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. Please be aware that for a working Mavericks auto configuration setup you need to have SSL enabled on the server. The non-SSL variant described below only works if you use the advanced CalDav configuration in Mavericks and enter the path by hand. If you just want to enter the hostname SSL is required. The same applies to iOS7 where SSL is always required.<br />
<br />
=== Alternative 1: Apache vhost (recommended) ===<br />
Please edit your site configuration file for OX so that ''' the existing OX configuration as well as the CalDAV/CardDav configuration are placed inside their own virtual hosts sections.'''.<br />
<br />
Please add the following entries before you existing VirtualHost entry. This is an <b>example</b> where MYSERVER.TLD is the domain-name of the ox-server:<br />
<br />
NameVirtualHost *:80<br />
<VirtualHost *:80><br />
ServerName dav.<MYSERVER.TLD><br />
ErrorLog /tmp/dav.err.log<br />
TransferLog /tmp/dav.access.log<br />
<br />
<Proxy balancer://oxserver-sync><br />
Order deny,allow<br />
Allow from all<br />
<br />
# for ajp http service<br />
BalancerMember ajp://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1<br />
# for grizzly http service<br />
#BalancerMember http://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1<br />
# uncomment this entry if you have a clustered setup and want to use the other nodes too<br />
#BalancerMember http://<ip-of-other-host>:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
<Proxy /><br />
Order allow,deny<br />
Allow from all<br />
ProxyPass balancer://oxserver-sync/servlet/dav/<br />
</Proxy><br />
</VirtualHost><br />
<br />
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.<br />
<br />
=== Alternative 2: Apache useragent detection ===<br />
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.<br />
<br />
$ vi /etc/apache2/ox6.conf<br />
<br />
RewriteEngine On<br />
RewriteCond %{HTTP_USER_AGENT} Calendar [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DataAccess [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DAVKit [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Lightning [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adresboek [OR]<br />
RewriteCond %{HTTP_USER_AGENT} dataaccessd [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Preferences [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adressbuch [OR]<br />
RewriteCond %{HTTP_USER_AGENT} AddressBook [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Address%20Book [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CalendarStore [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CoreDAV<br />
# select if you run ajp (proxy_ajp.conf) or grizzly (proxy_http.conf), here ajp is used:<br />
RewriteRule (.*) ajp://localhost:8009/servlet/dav$1 [P] # for ajp http service<br />
#RewriteRule (.*) http://localhost:8009/servlet/dav$1 [P] # for grizzly http service<br />
<br />
'''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.<br />
<br />
== Autodiscovery ==<br />
<br />
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]. <br />
<br />
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:<br />
<br />
_caldavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.<br />
_caldav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.<br />
_carddavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.<br />
_carddav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.<br />
<br />
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:<br />
<br />
RewriteEngine On<br />
RewriteCond %{REQUEST_URI} ^/\.well-known/caldav [OR]<br />
RewriteCond %{REQUEST_URI} ^/\.well-known/carddav<br />
RewriteRule (.*) / [L,R]<br />
<br />
== Which packages do I need? ==<br />
To get CalDAV and CardDAV up and running you need the following packages:<br />
<br />
In v6.20 and earlier:<br />
* 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.<br />
* 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.<br />
* open-xchange-carddav - The CardDAV interface exposing the users addressbook via carddav<br />
* open-xchange-caldav - The CalDAV inteface exposing the users calendars via caldav<br />
<br />
<br />
With v6.22 we have significantly reduced the number of packages necessary to install Open-Xchange Server.<br />
In v6.22 and later only one package is needed:<br />
* open-xchange-dav <br />
<br />
== Installation on OX App Suite ==<br />
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<br />
<br />
<br />
{{InstallPlugin|pluginname=open-xchange-caldav open-xchange-carddav open-xchange-webdav-acl open-xchange-webdav-directory |sopath=updates}}<br />
<br />
{{InstallPlugin|pluginname=open-xchange-dav|sopath=6.22/updates/backend|version=v6.22.x}}<br />
<br />
<br />
== CalDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files caldav.properties and caldav.yml:<br />
<br />
===com.openexchange.caldav.enabled===<br />
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:<br />
<br />
In v6.20 and earlier:<br />
<br />
/opt/open-xchange/etc/groupware/caldav.properties:<br />
com.openexchange.caldav.enabled=false<br />
<br />
/opt/open-xchange/etc/groupware/contextSets/caldav.yml<br />
premium:<br />
com.openexchange.caldav.enabled: true<br />
withTags: ucInfostore<br />
<br />
With v6.22 and up:<br />
<br />
/opt/open-xchange/etc/caldav.properties:<br />
com.openexchange.caldav.enabled=false<br />
<br />
/opt/open-xchange/etc/contextSets/caldav.yml<br />
premium:<br />
com.openexchange.caldav.enabled: true<br />
withTags: ucInfostore<br />
<br />
<br />
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.<br />
<br />
===com.openexchange.caldav.tree===<br />
Configures the ID of the folder tree used by the CalDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.caldav.interval.start===<br />
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". <br />
<br />
===com.openexchange.caldav.interval.end===<br />
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". <br />
<br />
===com.openexchange.caldav.url===<br />
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].<br />
<br />
<br />
== CardDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files carddav.properties and carddav.yml:<br />
<br />
===com.openexchange.carddav.enabled===<br />
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:<br />
<br />
/opt/open-xchange/etc/groupware/carddav.properties:<br />
com.openexchange.carddav.enabled=false<br />
<br />
/opt/open-xchange/etc/groupware/contextSets/carddav.yml<br />
premium:<br />
com.openexchange.carddav.enabled: true<br />
withTags: ucInfostore<br />
<br />
===com.openexchange.carddav.ignoreFolders===<br />
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.<br />
<br />
===com.openexchange.carddav.tree===<br />
Configures the ID of the folder tree used by the CardDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.carddav.exposedCollections===<br />
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'. <br />
<br />
===com.openexchange.carddav.userAgentForAggregatedCollection===<br />
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. <br />
<br />
===com.openexchange.carddav.reducedAggregatedCollection===<br />
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.<br />
<br />
[[Category: Clients]]<br />
[[Category: Administrator]]<br />
[[Category: AppSuite]]</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=Caldav_carddav_Bundles&diff=16631Caldav carddav Bundles2013-12-03T13:36:09Z<p>Dennis Sieben: /* Alternative 1: Apache vhost (recommended) */</p>
<hr />
<div>= Installation and Configuration of the CalDAV- and CardDAV-bundles =<br />
<br />
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.<br />
<br />
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. <br />
<br />
== User Guide and Client Configuration ==<br />
Please find further information regarding the client configuration at [[CalDAVClients]] and [[CardDAVClients]].<br />
<br />
== Webserver Configuration ==<br />
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. Please be aware that for a working Mavericks auto configuration setup you need to have SSL enabled on the server. The non-SSL variant described below only works if you use the advanced CalDav configuration in Mavericks and enter the path by hand. If you just want to enter the hostname SSL is required.<br />
<br />
=== Alternative 1: Apache vhost (recommended) ===<br />
Please edit your site configuration file for OX so that ''' the existing OX configuration as well as the CalDAV/CardDav configuration are placed inside their own virtual hosts sections.'''.<br />
<br />
Please add the following entries before you existing VirtualHost entry. This is an <b>example</b> where MYSERVER.TLD is the domain-name of the ox-server:<br />
<br />
NameVirtualHost *:80<br />
<VirtualHost *:80><br />
ServerName dav.<MYSERVER.TLD><br />
ErrorLog /tmp/dav.err.log<br />
TransferLog /tmp/dav.access.log<br />
<br />
<Proxy balancer://oxserver-sync><br />
Order deny,allow<br />
Allow from all<br />
<br />
# for ajp http service<br />
BalancerMember ajp://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1<br />
# for grizzly http service<br />
#BalancerMember http://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1<br />
# uncomment this entry if you have a clustered setup and want to use the other nodes too<br />
#BalancerMember http://<ip-of-other-host>:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
<Proxy /><br />
Order allow,deny<br />
Allow from all<br />
ProxyPass balancer://oxserver-sync/servlet/dav/<br />
</Proxy><br />
</VirtualHost><br />
<br />
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.<br />
<br />
=== Alternative 2: Apache useragent detection ===<br />
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.<br />
<br />
$ vi /etc/apache2/ox6.conf<br />
<br />
RewriteEngine On<br />
RewriteCond %{HTTP_USER_AGENT} Calendar [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DataAccess [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DAVKit [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Lightning [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adresboek [OR]<br />
RewriteCond %{HTTP_USER_AGENT} dataaccessd [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Preferences [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adressbuch [OR]<br />
RewriteCond %{HTTP_USER_AGENT} AddressBook [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Address%20Book [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CalendarStore [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CoreDAV<br />
# select if you run ajp (proxy_ajp.conf) or grizzly (proxy_http.conf), here ajp is used:<br />
RewriteRule (.*) ajp://localhost:8009/servlet/dav$1 [P] # for ajp http service<br />
#RewriteRule (.*) http://localhost:8009/servlet/dav$1 [P] # for grizzly http service<br />
<br />
'''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.<br />
<br />
== Autodiscovery ==<br />
<br />
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]. <br />
<br />
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:<br />
<br />
_caldavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.<br />
_caldav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.<br />
_carddavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.<br />
_carddav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.<br />
<br />
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:<br />
<br />
RewriteEngine On<br />
RewriteCond %{REQUEST_URI} ^/\.well-known/caldav [OR]<br />
RewriteCond %{REQUEST_URI} ^/\.well-known/carddav<br />
RewriteRule (.*) / [L,R]<br />
<br />
== Which packages do I need? ==<br />
To get CalDAV and CardDAV up and running you need the following packages:<br />
<br />
In v6.20 and earlier:<br />
* 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.<br />
* 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.<br />
* open-xchange-carddav - The CardDAV interface exposing the users addressbook via carddav<br />
* open-xchange-caldav - The CalDAV inteface exposing the users calendars via caldav<br />
<br />
<br />
With v6.22 we have significantly reduced the number of packages necessary to install Open-Xchange Server.<br />
In v6.22 and later only one package is needed:<br />
* open-xchange-dav <br />
<br />
== Installation on OX App Suite ==<br />
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<br />
<br />
<br />
{{InstallPlugin|pluginname=open-xchange-caldav open-xchange-carddav open-xchange-webdav-acl open-xchange-webdav-directory |sopath=updates}}<br />
<br />
{{InstallPlugin|pluginname=open-xchange-dav|sopath=6.22/updates/backend|version=v6.22.x}}<br />
<br />
<br />
== CalDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files caldav.properties and caldav.yml:<br />
<br />
===com.openexchange.caldav.enabled===<br />
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:<br />
<br />
In v6.20 and earlier:<br />
<br />
/opt/open-xchange/etc/groupware/caldav.properties:<br />
com.openexchange.caldav.enabled=false<br />
<br />
/opt/open-xchange/etc/groupware/contextSets/caldav.yml<br />
premium:<br />
com.openexchange.caldav.enabled: true<br />
withTags: ucInfostore<br />
<br />
With v6.22 and up:<br />
<br />
/opt/open-xchange/etc/caldav.properties:<br />
com.openexchange.caldav.enabled=false<br />
<br />
/opt/open-xchange/etc/contextSets/caldav.yml<br />
premium:<br />
com.openexchange.caldav.enabled: true<br />
withTags: ucInfostore<br />
<br />
<br />
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.<br />
<br />
===com.openexchange.caldav.tree===<br />
Configures the ID of the folder tree used by the CalDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.caldav.interval.start===<br />
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". <br />
<br />
===com.openexchange.caldav.interval.end===<br />
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". <br />
<br />
===com.openexchange.caldav.url===<br />
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].<br />
<br />
<br />
== CardDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files carddav.properties and carddav.yml:<br />
<br />
===com.openexchange.carddav.enabled===<br />
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:<br />
<br />
/opt/open-xchange/etc/groupware/carddav.properties:<br />
com.openexchange.carddav.enabled=false<br />
<br />
/opt/open-xchange/etc/groupware/contextSets/carddav.yml<br />
premium:<br />
com.openexchange.carddav.enabled: true<br />
withTags: ucInfostore<br />
<br />
===com.openexchange.carddav.ignoreFolders===<br />
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.<br />
<br />
===com.openexchange.carddav.tree===<br />
Configures the ID of the folder tree used by the CardDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.carddav.exposedCollections===<br />
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'. <br />
<br />
===com.openexchange.carddav.userAgentForAggregatedCollection===<br />
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. <br />
<br />
===com.openexchange.carddav.reducedAggregatedCollection===<br />
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.<br />
<br />
[[Category: Clients]]<br />
[[Category: Administrator]]<br />
[[Category: AppSuite]]</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=Caldav_carddav_Bundles&diff=16630Caldav carddav Bundles2013-12-03T12:50:21Z<p>Dennis Sieben: /* Webserver Configuration */</p>
<hr />
<div>= Installation and Configuration of the CalDAV- and CardDAV-bundles =<br />
<br />
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.<br />
<br />
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. <br />
<br />
== User Guide and Client Configuration ==<br />
Please find further information regarding the client configuration at [[CalDAVClients]] and [[CardDAVClients]].<br />
<br />
== Webserver Configuration ==<br />
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. Please be aware that for a working Mavericks auto configuration setup you need to have SSL enabled on the server. The non-SSL variant described below only works if you use the advanced CalDav configuration in Mavericks and enter the path by hand. If you just want to enter the hostname SSL is required.<br />
<br />
=== Alternative 1: Apache vhost (recommended) ===<br />
Please edit your site configuration file for OX so that ''' the existing OX configuration as well as the CalDAV/CardDav configuration are placed inside their own virtual hosts sections.'''.<br />
<br />
Please add the following entries before you existing VirtualHost entry. This is an <b>example</b> where MYSERVER.TLD is the domain-name of the ox-server:<br />
<br />
NameVirtualHost *:80<br />
<VirtualHost *:80><br />
ServerName dav.MYSERVER.TLD<br />
ErrorLog /tmp/dav.err.log<br />
TransferLog /tmp/dav.access.log<br />
<br />
<Proxy balancer://oxserver-sync><br />
Order deny,allow<br />
Allow from all<br />
<br />
# for ajp http service<br />
BalancerMember ajp://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1<br />
# for grizzly http service<br />
#BalancerMember http://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1<br />
# uncomment this entry if you have a clustered setup and want to use the other nodes too<br />
#BalancerMember http://<ip-of-other-host>:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
<Proxy /><br />
Order allow,deny<br />
Allow from all<br />
ProxyPass balancer://oxserver-sync/servlet/dav/<br />
</Proxy><br />
</VirtualHost><br />
<br />
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.<br />
<br />
=== Alternative 2: Apache useragent detection ===<br />
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.<br />
<br />
$ vi /etc/apache2/ox6.conf<br />
<br />
RewriteEngine On<br />
RewriteCond %{HTTP_USER_AGENT} Calendar [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DataAccess [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DAVKit [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Lightning [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adresboek [OR]<br />
RewriteCond %{HTTP_USER_AGENT} dataaccessd [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Preferences [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adressbuch [OR]<br />
RewriteCond %{HTTP_USER_AGENT} AddressBook [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Address%20Book [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CalendarStore [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CoreDAV<br />
# select if you run ajp (proxy_ajp.conf) or grizzly (proxy_http.conf), here ajp is used:<br />
RewriteRule (.*) ajp://localhost:8009/servlet/dav$1 [P] # for ajp http service<br />
#RewriteRule (.*) http://localhost:8009/servlet/dav$1 [P] # for grizzly http service<br />
<br />
'''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.<br />
<br />
== Autodiscovery ==<br />
<br />
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]. <br />
<br />
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:<br />
<br />
_caldavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.<br />
_caldav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.<br />
_carddavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.<br />
_carddav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.<br />
<br />
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:<br />
<br />
RewriteEngine On<br />
RewriteCond %{REQUEST_URI} ^/\.well-known/caldav [OR]<br />
RewriteCond %{REQUEST_URI} ^/\.well-known/carddav<br />
RewriteRule (.*) / [L,R]<br />
<br />
== Which packages do I need? ==<br />
To get CalDAV and CardDAV up and running you need the following packages:<br />
<br />
In v6.20 and earlier:<br />
* 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.<br />
* 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.<br />
* open-xchange-carddav - The CardDAV interface exposing the users addressbook via carddav<br />
* open-xchange-caldav - The CalDAV inteface exposing the users calendars via caldav<br />
<br />
<br />
With v6.22 we have significantly reduced the number of packages necessary to install Open-Xchange Server.<br />
In v6.22 and later only one package is needed:<br />
* open-xchange-dav <br />
<br />
== Installation on OX App Suite ==<br />
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<br />
<br />
<br />
{{InstallPlugin|pluginname=open-xchange-caldav open-xchange-carddav open-xchange-webdav-acl open-xchange-webdav-directory |sopath=updates}}<br />
<br />
{{InstallPlugin|pluginname=open-xchange-dav|sopath=6.22/updates/backend|version=v6.22.x}}<br />
<br />
<br />
== CalDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files caldav.properties and caldav.yml:<br />
<br />
===com.openexchange.caldav.enabled===<br />
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:<br />
<br />
In v6.20 and earlier:<br />
<br />
/opt/open-xchange/etc/groupware/caldav.properties:<br />
com.openexchange.caldav.enabled=false<br />
<br />
/opt/open-xchange/etc/groupware/contextSets/caldav.yml<br />
premium:<br />
com.openexchange.caldav.enabled: true<br />
withTags: ucInfostore<br />
<br />
With v6.22 and up:<br />
<br />
/opt/open-xchange/etc/caldav.properties:<br />
com.openexchange.caldav.enabled=false<br />
<br />
/opt/open-xchange/etc/contextSets/caldav.yml<br />
premium:<br />
com.openexchange.caldav.enabled: true<br />
withTags: ucInfostore<br />
<br />
<br />
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.<br />
<br />
===com.openexchange.caldav.tree===<br />
Configures the ID of the folder tree used by the CalDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.caldav.interval.start===<br />
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". <br />
<br />
===com.openexchange.caldav.interval.end===<br />
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". <br />
<br />
===com.openexchange.caldav.url===<br />
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].<br />
<br />
<br />
== CardDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files carddav.properties and carddav.yml:<br />
<br />
===com.openexchange.carddav.enabled===<br />
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:<br />
<br />
/opt/open-xchange/etc/groupware/carddav.properties:<br />
com.openexchange.carddav.enabled=false<br />
<br />
/opt/open-xchange/etc/groupware/contextSets/carddav.yml<br />
premium:<br />
com.openexchange.carddav.enabled: true<br />
withTags: ucInfostore<br />
<br />
===com.openexchange.carddav.ignoreFolders===<br />
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.<br />
<br />
===com.openexchange.carddav.tree===<br />
Configures the ID of the folder tree used by the CardDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.carddav.exposedCollections===<br />
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'. <br />
<br />
===com.openexchange.carddav.userAgentForAggregatedCollection===<br />
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. <br />
<br />
===com.openexchange.carddav.reducedAggregatedCollection===<br />
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.<br />
<br />
[[Category: Clients]]<br />
[[Category: Administrator]]<br />
[[Category: AppSuite]]</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Tutorial_1M&diff=16396AppSuite:OX Tutorial 1M2013-11-12T10:49:12Z<p>Dennis Sieben: </p>
<hr />
<div>= Tutorial: High Available OX App Suite Setup for up to 1 Milion users =<br />
<br />
'''This article describes what you need for a typical OX App Suite Setup for up to 1.000.000 Users, which is fully clustered, high available and scaling very flexible.'''<br />
<br />
It contains everything you need to:<br />
* Understand the design of the OX App Suite setup including additional services<br />
* Install the whole system based on the relevant articles<br />
* Find pointers to the next steps of integration<br />
<br />
<br />
= System Design =<br />
<br />
[[Image:SaaS-1M.jpg]]<br />
<br />
The system is designed to provide maximum functionality and availability with a minimum of necessary hardware. If the services on one OX server fail, this is transparently handled by the load balancer. If one MySQL server fails, it is sufficient to take over the IP address on the other MySQL server in the cluster to stay fully in operation.<br />
<br />
== Core Components for OX App Suite ==<br />
<br />
* Minimum two (recommended three) OX AppSuite servers (HW recommendation: 32GB RAM / 8 cores each)<br />
* Minimum one MySQL cluster with two servers in Master-Master configuration (HW recommendation: 32GB RAM / 8 cores each)<br />
* NFS Server to store documents and files<br />
* Recommended for more than 500.000 mailboxes: one OX App Suite server dedicated for user provisioning (HW recommendation: 16GB RAM / 4 cores each)<br />
<br />
== Infrastructure Components not delivered by OX ==<br />
<br />
* An email system providing IMAP and SMTP<br />
* A control panel for creation and administration of users<br />
* A Load Balancer in front of the OX servers (optional, recommended)<br />
<br />
= Overview Installation Steps =<br />
<br />
'''To deploy the described OX setup, the following steps need to be done. '''<br />
<br />
<br />
== Mandatory Steps ==<br />
# Initialize and configure MySQL database servers<br />
# Install and configure OX on all servers<br />
<br />
== Steps depending on your environment ==<br />
# Implement Load Balancer<br />
# Connect Control Panel<br />
# Connect Email System<br />
<br />
== Recommended Optional Next Steps ==<br />
# Automated Frontend Tests<br />
# Upsell Plugin<br />
# Mobile Autoconfiguration<br />
# Automatic FailOver<br />
# Branding<br />
<br />
<br />
= Mandatory Installation Steps - Instructions & Recommendations =<br />
<br />
<br />
'''The following steps need to be done in every case to get OX up and running:'''<br />
<br />
== Initialize and configure MySQL database on both servers ==<br />
<br />
MySQL will be configured as Master-Master configuration to ensure data consistency on both servers.<br />
If one machine fails, the other machine will take over all functionality.<br />
<br />
[[OXLoadBalancingClustering_Database|Database setup for clustered environments]]<br />
<br />
== Install and configure OX on both servers ==<br />
<br />
OX will be installed on minimum two servers. It will be configured to '''write''' to the '''first''' MySQL database and to '''read''' from the '''second''' MySQL database in one cluster. This will distribute the load during normal operation as smooth as possible. During FailOver the IP address of the failed MySQL server will be taken over to the working server, the system stays operable.<br />
<br />
[[AppSuite:OXLoadBalancingClustering_OXConfiguration|Open-Xchange setup and configuration for clustered environments]]<br />
<br />
The NFS server will be mounted on all machines and registered as filestore.<br />
<br />
[[OXLoadBalancingClustering_Filestore|Filestore setup for clustered environments]]<br />
<br />
When multiple Open-Xchange Servers are configured within a cluster Session and Loadbalancing needs to be set up.<br />
<br />
[[OXLoadBalancingClustering_SessionLoadbalancing|Session and Loadbalancing for clustered environments]]<br />
<br />
[[OXLoadBalancingClustering_NetworkConfiguration|Network configuration for clustered environments]]<br />
<br />
You also should install and configure the OXtender for Business Mobility:<br />
<br />
[[OXtender_for_Business_Mobility| exchange active sync configuration for Open-Xchange]]<br />
<br />
Let your users connect to their data from other services like Facebook, Twitter or LinkedIn by configuring the "SocialOX"<br />
<br />
[[SocialOX|SocialOX-Configuration]]<br />
<br />
= Installation Steps depending on your environment - Instructions & Recommendations =<br />
<br />
'''The following components need to be implemented in your environment.'''<br />
<br />
<br />
== Implement Load Balancer ==<br />
<br />
A load balancer in front of the OX servers is necessary for this deployment size. It needs to handle the requests if one OX server fails.<br />
<br />
If you already have a hardware load balancing solution in place, this can be used. OX is known to work with the standard load balancing solutions from BigIP, Barracuda, Foundry, ...<br />
<br />
If you do not have a load balancing solution already in place, we recommend to use [http://www.keepalived.org/ Keepalived] as reliable and cost effective solution.<br />
<br />
Read more about configuring [[Keepalived | Keepalived for Open-Xchange]]<br />
<br />
<br />
{{OX_HE_Tutorial_CP}}<br />
<br />
<br />
{{OX_HE_Tutorial_HGP}}<br />
<br />
<br />
{{OX_HE_Tutorial_POA}}<br />
<br />
<br />
{{OX_HE_Tutorial_Auth}}<br />
<br />
== Connect Email System ==<br />
<br />
Every email system providing IMAP and SMTP can be used as backend to OX. Best experiences are made with the widespread Linux based IMAP servers [http://dovecot.org/ Dovecot], [http://www.cyrusimap.org/ Cyrus] or [http://www.courier-mta.org/imap/ Courier]. <br />
<br />
Other IMAP servers need to be tested thoroughly before going into production.<br />
<br />
There are several possibilities to implement the Email system:<br />
<br />
# You already have an email system available: Nothing needs to be done, it just needs to be configured<br />
# You use Parallels Automation (POA): Nothing special needs to be done, everything you need is contained in the APS package<br />
# You want to setup a new Email system: It is recommended to use Dovecot, as this is very stable, fast, feature rich and easy to scale<br />
<br />
<br />
{{OX_HE_Tutorial_Dovecot}}<br />
<br />
<br />
{{AppSuite:OX_Tutorial_Next}}</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Tutorial_100K&diff=16395AppSuite:OX Tutorial 100K2013-11-12T10:48:16Z<p>Dennis Sieben: </p>
<hr />
<div>= Tutorial: High Available OX AppSuite Setup for up to 100.000 users =<br />
<br />
'''This article describes what you need for a typical OX AppSuite Setup for up to 100.000 Users, which is fully clustered and high available.'''<br />
<br />
It contains everything you need to:<br />
* Understand the design of the OX AppSuite setup including additional services<br />
* Install the whole system based on the relevant articles<br />
* Find pointers to the next steps of integration<br />
<br />
<br />
= System Design =<br />
<br />
[[Image:SaaS-100k-1.jpg]]<br />
<br />
The system is designed to provide maximum functionality and availability with a minimum of necessary hardware. If the services on one server fail, it is enough to take over the IP address to the other machine and service will stay up and running.<br />
<br />
== Core Components for OX AppSuite ==<br />
<br />
* Two OX AppSuite servers (HW recommendation: 16GB RAM / 4 cores each)<br />
* MySQL installed directly on these server <br />
* NFS Server to store documents and files<br />
<br />
== Infrastructure Components not delivered by OX ==<br />
<br />
* An email system providing IMAP and SMTP<br />
* A control panel for creation and administration of users<br />
* A Load Balancer in front of the OX servers (optional, recommended)<br />
<br />
= Overview Installation Steps =<br />
<br />
'''To deploy the described OX setup, the following steps need to be done. '''<br />
<br />
<br />
== Mandatory Steps ==<br />
# Initialize and configure MySQL database on both servers<br />
# Install and configure OX on both servers<br />
<br />
== Steps depending on your environment ==<br />
# Implement Load Balancer<br />
# Connect Control Panel<br />
# Connect Email System<br />
<br />
== Recommended Optional Next Steps ==<br />
# Automated Frontend Tests<br />
# Upsell Plugin<br />
# Mobile Autoconfiguration<br />
# Automatic FailOver<br />
# Branding<br />
<br />
<br />
= Mandatory Installation Steps - Instructions & Recommendations =<br />
<br />
<br />
'''The following steps need to be done in every case to get OX up and running:'''<br />
<br />
== Initialize and configure MySQL database on both servers ==<br />
<br />
MySQL will run on both servers. MySQL will be configured as Master-Master configuration to ensure data consistency on both servers.<br />
If one machine fails, the other machine will take over all functionality.<br />
<br />
[[OXLoadBalancingClustering_Database|Database setup for clustered environments]]<br />
<br />
== Install and configure OX on both servers ==<br />
<br />
OX will be installed on both servers. It will be configured to '''write''' to the '''first''' MySQL database and to '''read''' from the '''second''' MySQL database. This will distribute the load during normal operation as smooth as possible. During FailOver the IP address of the failed server will be taken over to the working server, the system stays operable.<br />
<br />
[[AppSuite:OXLoadBalancingClustering_OXConfiguration|Open-Xchange setup and configuration for clustered environments]]<br />
<br />
The NFS server will be mounted on both machines and registered as filestore.<br />
<br />
[[OXLoadBalancingClustering_Filestore|Filestore setup for clustered environments]]<br />
<br />
When multiple Open-Xchange Servers are configured within a cluster Session and Loadbalancing needs to be set up.<br />
<br />
[[OXLoadBalancingClustering_SessionLoadbalancing|Session and Loadbalancing for clustered environments]]<br />
<br />
[[OXLoadBalancingClustering_NetworkConfiguration|Network configuration for clustered environments]]<br />
<br />
You also should install and configure the OXtender for Business Mobility<br />
<br />
[[OXtender_for_Business_Mobility_Installation_Guide|Installation of the OXtender for Business Mobility]]<br />
<br />
Let your users connect to their data from other services like Facebook, Twitter or LinkedIn by configuring the "SocialOX"<br />
<br />
[[SocialOX|SocialOX-Configuration]]<br />
<br />
= Installation Steps depending on your environment - Instructions & Recommendations =<br />
<br />
'''The following components need to be implemented in your environment.'''<br />
<br />
<br />
== Implement Load Balancer ==<br />
<br />
A load balancer in front of the OX servers is recommended, but optional in this deployment size. (In small environments, DNS Round Robin may be sufficient).<br />
<br />
If you already have a hardware load balancing solution in place, this can be used. OX is known to work with the standard load balancing solutions from BigIP, Barracuda, Foundry, ...<br />
<br />
If you do not have a load balancing solution already in place, we recommend to use [http://www.keepalived.org/ Keepalived] as reliable and cost effective solution.<br />
<br />
Read more about configuring [[Keepalived | Keepalived for Open-Xchange]]<br />
<br />
<br />
{{OX_HE_Tutorial_CP}}<br />
<br />
<br />
{{OX_HE_Tutorial_HGP}}<br />
<br />
<br />
{{OX_HE_Tutorial_POA}}<br />
<br />
<br />
{{OX_HE_Tutorial_Auth}}<br />
<br />
<br />
== Connect Email System ==<br />
<br />
Every email system providing IMAP and SMTP can be used as backend to OX. Best experiences are made with the widespread Linux based IMAP servers [http://dovecot.org/ Dovecot], [http://www.cyrusimap.org/ Cyrus] or [http://www.courier-mta.org/imap/ Courier]. <br />
<br />
Other IMAP servers need to be tested thoroughly before going into production.<br />
<br />
There are several possibilities to implement the Email system:<br />
<br />
# You already have an email system available: Nothing needs to be done, it just needs to be configured<br />
# You use Parallels Automation (POA): Nothing special needs to be done, everything you need is contained in the APS package<br />
# You want to setup a new Email system: It is recommended to use Dovecot, as this is very stable, fast, feature rich and easy to scale<br />
<br />
<br />
{{OX_HE_Tutorial_Dovecot}}<br />
<br />
<br />
{{AppSuite:OX_Tutorial_Next}}<br />
<br />
<br />
{{OX_HE_Tutorial_FailOver}}</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:OXLoadBalancingClustering_OXConfiguration&diff=16394AppSuite:OXLoadBalancingClustering OXConfiguration2013-11-12T10:47:31Z<p>Dennis Sieben: Created page with "{{OXLoadBalancingClustering_OXConfiguration|release=appsuite}}"</p>
<hr />
<div>{{OXLoadBalancingClustering_OXConfiguration|release=appsuite}}</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=Template:OXLoadBalancingClustering_OXConfiguration&diff=16393Template:OXLoadBalancingClustering OXConfiguration2013-11-12T10:42:10Z<p>Dennis Sieben: /* Configuring Open-Xchange Server */</p>
<hr />
<div>== Configuring Open-Xchange Server ==<br />
Install all relevant Open-Xchange Server packages to both groupware nodes after adding the Open-Xchange software repository to your package manages configuration. Corresponding installation instructions for your distribution can be found here:<br />
<br />
{{#if:{{{release|}}}|<br />
{{#ifeq:{{{release|}}}|6.22|<br />
<br />
* [[Open-Xchange_Installation_Guide_for_Debian_6.0_622|Download and Installation Guide for Debian GNU/Linux 6.0 (Squeeze)]]<br />
* [[Open-Xchange_Installation_Guide_for_SLES11_622|Download and Installation Guide for SUSE Linux Enterprise Server 11]]<br />
* [[Open-Xchange_Installation_Guide_for_RHEL6_622|Download and Installation Guide for RedHat Enterprise Linux 6]]<br />
* [[Open-Xchange Installation Guide for CentOS 6_622|Download and Installation Guide for CentOS 6]]<br />
<br />
|{{#ifeq:{{{release|}}}|appsuite|<br />
<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_6.0|Download and Installation Guide for Debian GNU/Linux 6.0 (Squeeze)]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_7.0|Download and Installation Guide for Debian GNU/Linux 7.0 (Wheezy)]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_SLES11|Download and Installation Guide for SUSE Linux Enterprise Server 11]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_RHEL6|Download and Installation Guide for RedHat Enterprise Linux 6]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_CentOS_6|Download and Installation Guide for CentOS 6]]<br />
<br />
}}|}}| {{#!:<br />
<br />
* [[Open-Xchange_Installation_Guide_for_Debian_6.0_622|Download and Installation Guide for Debian GNU/Linux 6.0 (Squeeze)]]<br />
* [[Open-Xchange_Installation_Guide_for_SLES11_622|Download and Installation Guide for SUSE Linux Enterprise Server 11]]<br />
* [[Open-Xchange_Installation_Guide_for_RHEL6_622|Download and Installation Guide for RedHat Enterprise Linux 6]]<br />
* [[Open-Xchange Installation Guide for CentOS 6_622|Download and Installation Guide for CentOS 6]]<br />
<br />
}}}}<br />
<br />
It's also possible to install backend and frontend components on each node. The difference is that a backend only on each node demands separate machines which the fronend in front of the backend nodes, while you only need a load balancer in front of the nodes if you install the backend and the frontend on each node.<br />
<br />
Create the ''configdb'' database at the MySQL Master. This step does only need to be performed on one of the Open-Xchange Server nodes.<br />
$ /opt/open-xchange/sbin/initconfigdb --configdb-user=openexchange --configdb-pass=secret --configdb-host=10.20.30.217<br />
<br />
Setup the Open-Xchange Server configuration. This step needs to be performed on 'both' groupware nodes. Note that the ''--jkroute'' parameter must equal the ''route'' parameter at the web servers ''proxy_ajp'' load balancing configuration of the specific server.<br />
Node 1:<br />
$ /opt/open-xchange/sbin/oxinstaller --servername=oxserver --configdb-readhost=10.20.30.219 --configdb-writehost=10.20.30.217 --configdb-user=openexchange --master-pass=secret --configdb-pass=secret --jkroute=OX1 --ajp-bind-port=*<br />
Node 2:<br />
$ /opt/open-xchange/sbin/oxinstaller --servername=oxserver --configdb-readhost=10.20.30.219 --configdb-writehost=10.20.30.217 --configdb-user=openexchange --master-pass=secret --configdb-pass=secret --jkroute=OX2 --ajp-bind-port=*<br />
<br />
Startup the Administration Daemon on one of the nodes. Wait some seconds until the Open-Xchange Administration Daemon is started completely.<br />
$ /etc/init.d/open-xchange-admin start<br />
<br />
Now register the Open-Xchange Server at the database. Note that a ''server'' is a whole cluster in this case. This step does only need to be performed on one of the Open-Xchange Server nodes.<br />
$ /opt/open-xchange/sbin/registerserver -n oxserver -A oxadminmaster -P secret<br />
<br />
Register the filestorage. This step does only need to be performed on one of the Open-Xchange Server nodes. Note that the NFS export must be mounted to the same path on both groupware nodes.<br />
$ /opt/open-xchange/sbin/registerfilestore -A oxadminmaster -P secret -t file:///var/opt/filestore<br />
<br />
Now register the MySQL Master database in configdb. This step does only need to be performed on one of the Open-Xchange Server nodes.<br />
$ /opt/open-xchange/sbin/registerdatabase -A oxadminmaster -P secret --name oxdatabase --hostname 10.20.30.217 --dbuser openexchange --dbpasswd secret --master true<br />
database 4 registered<br />
<br />
Check the returned database ID which is 4 in this case. This value is required to register the MySQL Slave database in configdb. This step does only need to be performed on one of the Open-Xchange Server nodes.<br />
$ /opt/open-xchange/sbin/registerdatabase -A oxadminmaster -P secret --name oxdatabase_slave --hostname 10.20.30.219 --dbuser openexchange --dbpasswd secret --master false --masterid=4<br />
<br />
Now start Open-Xchange Server on both groupware nodes.<br />
$ /etc/init.d/open-xchange-groupware start<br />
<br />
Create a new context and a testuser<br />
$ /opt/open-xchange/sbin/createcontext -A oxadminmaster -P secret -c 1 -u oxadmin -d "Context Admin" -g Admin -s User -p secret -L defaultcontext -e oxadmin@example.com -q 1024 --access-combination-name=all<br />
$ /opt/open-xchange/sbin/createuser -c 1 -A oxadmin -P secret -u testuser -d "Test User" -g Test -s User -p secret -e testuser@example.com<br />
<br />
=== Test Session load balancing ===<br />
Apache is configured to use a 50:50 balancing between both Open-Xchange Servers. Now that they are up and running its time to check if this balancing works. This can be done by simply watching the Open-Xchange Server log files while a user logs in.<br />
Execute ''tail'' to the ''open-xchange.log.0'' file on both servers. Then login with the testuser, one of the servers log file should show something like<br />
$ tail -fn200 /var/log/open-xchange/open-xchange.log.0<br />
[...]<br />
INFO: Session created. ID: 31060fc80b9e44d38148ef4d5d19963d, Context: 1, User: 3<br />
<br />
Then logout and login again. This time, the session should be created on the other server. On the client side, the JSESSIONID cookie at the browser shows evidence on which server the user has logged in by the trailing ".OX-" identifier. This identifier is set by Open-Xchange Server based on its AJP_JVM_ROUTE attribute.</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Tutorial_1M&diff=16390AppSuite:OX Tutorial 1M2013-11-11T15:57:36Z<p>Dennis Sieben: Created page with "= Tutorial: High Available OX App Suite Setup for up to 1 Milion users = '''This article describes what you need for a typical OX App Suite Setup for up to 1.000.000 Users, w..."</p>
<hr />
<div>= Tutorial: High Available OX App Suite Setup for up to 1 Milion users =<br />
<br />
'''This article describes what you need for a typical OX App Suite Setup for up to 1.000.000 Users, which is fully clustered, high available and scaling very flexible.'''<br />
<br />
It contains everything you need to:<br />
* Understand the design of the OX App Suite setup including additional services<br />
* Install the whole system based on the relevant articles<br />
* Find pointers to the next steps of integration<br />
<br />
<br />
= System Design =<br />
<br />
[[Image:SaaS-1M.jpg]]<br />
<br />
The system is designed to provide maximum functionality and availability with a minimum of necessary hardware. If the services on one OX server fail, this is transparently handled by the load balancer. If one MySQL server fails, it is sufficient to take over the IP address on the other MySQL server in the cluster to stay fully in operation.<br />
<br />
== Core Components for OX App Suite ==<br />
<br />
* Minimum two (recommended three) OX AppSuite servers (HW recommendation: 32GB RAM / 8 cores each)<br />
* Minimum one MySQL cluster with two servers in Master-Master configuration (HW recommendation: 32GB RAM / 8 cores each)<br />
* NFS Server to store documents and files<br />
* Recommended for more than 500.000 mailboxes: one OX App Suite server dedicated for user provisioning (HW recommendation: 16GB RAM / 4 cores each)<br />
<br />
== Infrastructure Components not delivered by OX ==<br />
<br />
* An email system providing IMAP and SMTP<br />
* A control panel for creation and administration of users<br />
* A Load Balancer in front of the OX servers (optional, recommended)<br />
<br />
= Overview Installation Steps =<br />
<br />
'''To deploy the described OX setup, the following steps need to be done. '''<br />
<br />
<br />
== Mandatory Steps ==<br />
# Initialize and configure MySQL database servers<br />
# Install and configure OX on all servers<br />
<br />
== Steps depending on your environment ==<br />
# Implement Load Balancer<br />
# Connect Control Panel<br />
# Connect Email System<br />
<br />
== Recommended Optional Next Steps ==<br />
# Automated Frontend Tests<br />
# Upsell Plugin<br />
# Mobile Autoconfiguration<br />
# Automatic FailOver<br />
# Branding<br />
<br />
<br />
= Mandatory Installation Steps - Instructions & Recommendations =<br />
<br />
<br />
'''The following steps need to be done in every case to get OX up and running:'''<br />
<br />
== Initialize and configure MySQL database on both servers ==<br />
<br />
MySQL will be configured as Master-Master configuration to ensure data consistency on both servers.<br />
If one machine fails, the other machine will take over all functionality.<br />
<br />
[[OXLoadBalancingClustering_Database|Database setup for clustered environments]]<br />
<br />
== Install and configure OX on both servers ==<br />
<br />
OX will be installed on minimum two servers. It will be configured to '''write''' to the '''first''' MySQL database and to '''read''' from the '''second''' MySQL database in one cluster. This will distribute the load during normal operation as smooth as possible. During FailOver the IP address of the failed MySQL server will be taken over to the working server, the system stays operable.<br />
<br />
[[OXLoadBalancingClustering_OXConfiguration|Open-Xchange setup and configuration for clustered environments]]<br />
<br />
The NFS server will be mounted on all machines and registered as filestore.<br />
<br />
[[OXLoadBalancingClustering_Filestore|Filestore setup for clustered environments]]<br />
<br />
When multiple Open-Xchange Servers are configured within a cluster Session and Loadbalancing needs to be set up.<br />
<br />
[[OXLoadBalancingClustering_SessionLoadbalancing|Session and Loadbalancing for clustered environments]]<br />
<br />
[[OXLoadBalancingClustering_NetworkConfiguration|Network configuration for clustered environments]]<br />
<br />
You also should install and configure the OXtender for Business Mobility:<br />
<br />
[[OXtender_for_Business_Mobility| exchange active sync configuration for Open-Xchange]]<br />
<br />
Let your users connect to their data from other services like Facebook, Twitter or LinkedIn by configuring the "SocialOX"<br />
<br />
[[SocialOX|SocialOX-Configuration]]<br />
<br />
= Installation Steps depending on your environment - Instructions & Recommendations =<br />
<br />
'''The following components need to be implemented in your environment.'''<br />
<br />
<br />
== Implement Load Balancer ==<br />
<br />
A load balancer in front of the OX servers is necessary for this deployment size. It needs to handle the requests if one OX server fails.<br />
<br />
If you already have a hardware load balancing solution in place, this can be used. OX is known to work with the standard load balancing solutions from BigIP, Barracuda, Foundry, ...<br />
<br />
If you do not have a load balancing solution already in place, we recommend to use [http://www.keepalived.org/ Keepalived] as reliable and cost effective solution.<br />
<br />
Read more about configuring [[Keepalived | Keepalived for Open-Xchange]]<br />
<br />
<br />
{{OX_HE_Tutorial_CP}}<br />
<br />
<br />
{{OX_HE_Tutorial_HGP}}<br />
<br />
<br />
{{OX_HE_Tutorial_POA}}<br />
<br />
<br />
{{OX_HE_Tutorial_Auth}}<br />
<br />
== Connect Email System ==<br />
<br />
Every email system providing IMAP and SMTP can be used as backend to OX. Best experiences are made with the widespread Linux based IMAP servers [http://dovecot.org/ Dovecot], [http://www.cyrusimap.org/ Cyrus] or [http://www.courier-mta.org/imap/ Courier]. <br />
<br />
Other IMAP servers need to be tested thoroughly before going into production.<br />
<br />
There are several possibilities to implement the Email system:<br />
<br />
# You already have an email system available: Nothing needs to be done, it just needs to be configured<br />
# You use Parallels Automation (POA): Nothing special needs to be done, everything you need is contained in the APS package<br />
# You want to setup a new Email system: It is recommended to use Dovecot, as this is very stable, fast, feature rich and easy to scale<br />
<br />
<br />
{{OX_HE_Tutorial_Dovecot}}<br />
<br />
<br />
{{AppSuite:OX_Tutorial_Next}}</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Tutorial_100K&diff=16388AppSuite:OX Tutorial 100K2013-11-11T15:24:47Z<p>Dennis Sieben: Created page with "= Tutorial: High Available OX AppSuite Setup for up to 100.000 users = '''This article describes what you need for a typical OX AppSuite Setup for up to 100.000 Users, which ..."</p>
<hr />
<div>= Tutorial: High Available OX AppSuite Setup for up to 100.000 users =<br />
<br />
'''This article describes what you need for a typical OX AppSuite Setup for up to 100.000 Users, which is fully clustered and high available.'''<br />
<br />
It contains everything you need to:<br />
* Understand the design of the OX AppSuite setup including additional services<br />
* Install the whole system based on the relevant articles<br />
* Find pointers to the next steps of integration<br />
<br />
<br />
= System Design =<br />
<br />
[[Image:SaaS-100k-1.jpg]]<br />
<br />
The system is designed to provide maximum functionality and availability with a minimum of necessary hardware. If the services on one server fail, it is enough to take over the IP address to the other machine and service will stay up and running.<br />
<br />
== Core Components for OX AppSuite ==<br />
<br />
* Two OX AppSuite servers (HW recommendation: 16GB RAM / 4 cores each)<br />
* MySQL installed directly on these server <br />
* NFS Server to store documents and files<br />
<br />
== Infrastructure Components not delivered by OX ==<br />
<br />
* An email system providing IMAP and SMTP<br />
* A control panel for creation and administration of users<br />
* A Load Balancer in front of the OX servers (optional, recommended)<br />
<br />
= Overview Installation Steps =<br />
<br />
'''To deploy the described OX setup, the following steps need to be done. '''<br />
<br />
<br />
== Mandatory Steps ==<br />
# Initialize and configure MySQL database on both servers<br />
# Install and configure OX on both servers<br />
<br />
== Steps depending on your environment ==<br />
# Implement Load Balancer<br />
# Connect Control Panel<br />
# Connect Email System<br />
<br />
== Recommended Optional Next Steps ==<br />
# Automated Frontend Tests<br />
# Upsell Plugin<br />
# Mobile Autoconfiguration<br />
# Automatic FailOver<br />
# Branding<br />
<br />
<br />
= Mandatory Installation Steps - Instructions & Recommendations =<br />
<br />
<br />
'''The following steps need to be done in every case to get OX up and running:'''<br />
<br />
== Initialize and configure MySQL database on both servers ==<br />
<br />
MySQL will run on both servers. MySQL will be configured as Master-Master configuration to ensure data consistency on both servers.<br />
If one machine fails, the other machine will take over all functionality.<br />
<br />
[[OXLoadBalancingClustering_Database|Database setup for clustered environments]]<br />
<br />
== Install and configure OX on both servers ==<br />
<br />
OX will be installed on both servers. It will be configured to '''write''' to the '''first''' MySQL database and to '''read''' from the '''second''' MySQL database. This will distribute the load during normal operation as smooth as possible. During FailOver the IP address of the failed server will be taken over to the working server, the system stays operable.<br />
<br />
[[OXLoadBalancingClustering_OXConfiguration|Open-Xchange setup and configuration for clustered environments]]<br />
<br />
The NFS server will be mounted on both machines and registered as filestore.<br />
<br />
[[OXLoadBalancingClustering_Filestore|Filestore setup for clustered environments]]<br />
<br />
When multiple Open-Xchange Servers are configured within a cluster Session and Loadbalancing needs to be set up.<br />
<br />
[[OXLoadBalancingClustering_SessionLoadbalancing|Session and Loadbalancing for clustered environments]]<br />
<br />
[[OXLoadBalancingClustering_NetworkConfiguration|Network configuration for clustered environments]]<br />
<br />
You also should install and configure the OXtender for Business Mobility<br />
<br />
[[OXtender_for_Business_Mobility_Installation_Guide|Installation of the OXtender for Business Mobility]]<br />
<br />
Let your users connect to their data from other services like Facebook, Twitter or LinkedIn by configuring the "SocialOX"<br />
<br />
[[SocialOX|SocialOX-Configuration]]<br />
<br />
= Installation Steps depending on your environment - Instructions & Recommendations =<br />
<br />
'''The following components need to be implemented in your environment.'''<br />
<br />
<br />
== Implement Load Balancer ==<br />
<br />
A load balancer in front of the OX servers is recommended, but optional in this deployment size. (In small environments, DNS Round Robin may be sufficient).<br />
<br />
If you already have a hardware load balancing solution in place, this can be used. OX is known to work with the standard load balancing solutions from BigIP, Barracuda, Foundry, ...<br />
<br />
If you do not have a load balancing solution already in place, we recommend to use [http://www.keepalived.org/ Keepalived] as reliable and cost effective solution.<br />
<br />
Read more about configuring [[Keepalived | Keepalived for Open-Xchange]]<br />
<br />
<br />
{{OX_HE_Tutorial_CP}}<br />
<br />
<br />
{{OX_HE_Tutorial_HGP}}<br />
<br />
<br />
{{OX_HE_Tutorial_POA}}<br />
<br />
<br />
{{OX_HE_Tutorial_Auth}}<br />
<br />
<br />
== Connect Email System ==<br />
<br />
Every email system providing IMAP and SMTP can be used as backend to OX. Best experiences are made with the widespread Linux based IMAP servers [http://dovecot.org/ Dovecot], [http://www.cyrusimap.org/ Cyrus] or [http://www.courier-mta.org/imap/ Courier]. <br />
<br />
Other IMAP servers need to be tested thoroughly before going into production.<br />
<br />
There are several possibilities to implement the Email system:<br />
<br />
# You already have an email system available: Nothing needs to be done, it just needs to be configured<br />
# You use Parallels Automation (POA): Nothing special needs to be done, everything you need is contained in the APS package<br />
# You want to setup a new Email system: It is recommended to use Dovecot, as this is very stable, fast, feature rich and easy to scale<br />
<br />
<br />
{{OX_HE_Tutorial_Dovecot}}<br />
<br />
<br />
{{AppSuite:OX_Tutorial_Next}}<br />
<br />
<br />
{{OX_HE_Tutorial_FailOver}}</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Tutorial_10K&diff=16386AppSuite:OX Tutorial 10K2013-11-11T15:03:33Z<p>Dennis Sieben: </p>
<hr />
<div>= Tutorial: OX AppSuite Setup for up to 10.000 users =<br />
<br />
'''This article describes what you need for a typical OX AppSuite Setup for up to 10.000 Users with minimal efforts.'''<br />
<br />
It contains everything you need to:<br />
* Understand the design of the OX AppSuite setup including additional services<br />
* Install the whole system based on the relevant articles<br />
* Find pointers to the next steps of integration<br />
<br />
<br />
= System Design =<br />
<br />
[[Image:SaaS-10k.jpg]]<br />
<br />
The system is designed to provide maximum functionality with a minimum of necessary hardware. All OX services are running on one single machine.<br />
<br />
<br />
== Core Components for OX AppSuite ==<br />
<br />
* One OX AppSuite server (HW recommendation: 16GB RAM / 4 cores)<br />
* MySQL installed directly on this server <br />
* Optional: NFS Server to store documents and files<br />
<br />
<br />
== Infrastructure Components not delivered by OX ==<br />
<br />
* An email system providing IMAP and SMTP<br />
* A control panel for creation and administration of users<br />
<br />
<br />
= Overview Installation Steps =<br />
<br />
'''To deploy the described OX setup, the following steps need to be done. '''<br />
<br />
<br />
== Mandatory Steps ==<br />
# Initialize and configure MySQL database<br />
# Install and configure OX service<br />
<br />
== Steps depending on your environment ==<br />
# Connect Control Panel<br />
# Connect Email System<br />
<br />
== Recommended Optional Next Steps ==<br />
# Automated Frontend Tests<br />
# Upsell Plugin<br />
# Mobile Autoconfiguration<br />
# Branding<br />
<br />
<br />
= Mandatory Installation Steps - Instructions & Recommendations =<br />
<br />
<br />
'''The following steps need to be done in every case to get OX up and running:'''<br />
<br />
== Install and configure OX ==<br />
<br />
OX will be installed on the server.<br />
<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_6.0|Download and Installation Guide for Debian GNU/Linux 6.0 (Squeeze)]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_7.0|Download and Installation Guide for Debian GNU/Linux 7.0 (Wheezy)]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_SLES11|Download and Installation Guide for SUSE Linux Enterprise Server 11]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_RHEL6|Download and Installation Guide for RedHat Enterprise Linux 6]]<br />
<br />
You also should install and configure the OXtender for Business Mobility<br />
<br />
[[AppSuite:OXtender_for_Business_Mobility_Installation_Guide|Installation of the OXtender for Business Mobility]]<br />
<br />
Let your users connect to their data from other services like Facebook, Twitter or LinkedIn by configuring the "SocialOX"<br />
<br />
[[SocialOX|SocialOX-Configuration]]<br />
<br />
= Installation Steps depending on your environment - Instructions & Recommendations =<br />
<br />
'''The following components need to be implemented in your environment.'''<br />
<br />
<br />
{{OX_HE_Tutorial_CP}}<br />
<br />
<br />
{{OX_HE_Tutorial_HGP}}<br />
<br />
<br />
{{OX_HE_Tutorial_Plesk}}<br />
<br />
<br />
{{OX_HE_Tutorial_Auth}}<br />
<br />
<br />
== Connect Email System ==<br />
<br />
Every email system providing IMAP and SMTP can be used as backend to OX. Best experiences are made with the widespread Linux based IMAP servers [http://dovecot.org/ Dovecot], [http://www.cyrusimap.org/ Cyrus] or [http://www.courier-mta.org/imap/ Courier]. <br />
<br />
Other IMAP servers need to be tested thoroughly before going into production.<br />
<br />
There are several possibilities to implement the Email system:<br />
<br />
# You already have an email system available: Nothing needs to be done, it just needs to be configured<br />
# You use Plesk Panel: Nothing special needs to be done, everything you need is contained in the OXtender for Plesk<br />
# You want to setup a new Email system: It is recommended to use Dovecot, as this is very stable, fast, feature rich and easy to scale<br />
<br />
<br />
{{OX_HE_Tutorial_Dovecot}}<br />
<br />
<br />
{{AppSuite:OX_Tutorial_Next}}</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Tutorial_Next&diff=16385AppSuite:OX Tutorial Next2013-11-11T15:02:19Z<p>Dennis Sieben: Created page with "= Recommended Optional Next Steps = You will find plenty of additional documentation for customization of OX in our knowledge base [http://oxpedia.org] When the main setup i..."</p>
<hr />
<div>= Recommended Optional Next Steps =<br />
<br />
You will find plenty of additional documentation for customization of OX in our knowledge base [http://oxpedia.org]<br />
<br />
When the main setup is completed, we recommend to start with the following articles to enhance your system and to become more attractive for your users.<br />
<br />
<br />
== Monitoring / Statistics ==<br />
<br />
It is recommended to implement at least a minimal monitoring/Statistics solution to get an overview of the systems health. If you have a support contract with Open-Xchange, it is very helpful, if the support can access the monitoring graphs. There are example scripts for a basic monitoring with [[http://munin-monitoring.org/ Munin]] available.<br />
<br />
Read more about installing and configuring [[OX_munin_scripts|Munin scripts for Open-Xchange]]<br />
<br />
<br />
== Backup ==<br />
<br />
It is recommended to run regular backups for your OX installation. This can be done with every backup solution for Linux.<br />
<br />
Read more about [[Open-Xchange_backup|Backup your Open-Xchange installation]]</div>Dennis Siebenhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Tutorial_10K&diff=16384AppSuite:OX Tutorial 10K2013-11-11T15:01:17Z<p>Dennis Sieben: </p>
<hr />
<div>= Tutorial: OX AppSuite Setup for up to 10.000 users =<br />
<br />
'''This article describes what you need for a typical OX AppSuite Setup for up to 10.000 Users with minimal efforts.'''<br />
<br />
It contains everything you need to:<br />
* Understand the design of the OX AppSuite setup including additional services<br />
* Install the whole system based on the relevant articles<br />
* Find pointers to the next steps of integration<br />
<br />
<br />
= System Design =<br />
<br />
[[Image:SaaS-10k.jpg]]<br />
<br />
The system is designed to provide maximum functionality with a minimum of necessary hardware. All OX services are running on one single machine.<br />
<br />
<br />
== Core Components for OX AppSuite ==<br />
<br />
* One OX AppSuite server (HW recommendation: 16GB RAM / 4 cores)<br />
* MySQL installed directly on this server <br />
* Optional: NFS Server to store documents and files<br />
<br />
== Infrastructure Components not delivered by OX ==<br />
<br />
* An email system providing IMAP and SMTP<br />
* A control panel for creation and administration of users<br />
<br />
= Overview Installation Steps =<br />
<br />
'''To deploy the described OX setup, the following steps need to be done. '''<br />
<br />
<br />
== Mandatory Steps ==<br />
# Initialize and configure MySQL database<br />
# Install and configure OX service<br />
<br />
== Steps depending on your environment ==<br />
# Connect Control Panel<br />
# Connect Email System<br />
<br />
== Recommended Optional Next Steps ==<br />
# Automated Frontend Tests<br />
# Upsell Plugin<br />
# Mobile Autoconfiguration<br />
# Branding<br />
<br />
<br />
= Mandatory Installation Steps - Instructions & Recommendations =<br />
<br />
<br />
'''The following steps need to be done in every case to get OX up and running:'''<br />
<br />
== Install and configure OX ==<br />
<br />
OX will be installed on the server.<br />
<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_6.0|Download and Installation Guide for Debian GNU/Linux 6.0 (Squeeze)]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_7.0|Download and Installation Guide for Debian GNU/Linux 7.0 (Wheezy)]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_SLES11|Download and Installation Guide for SUSE Linux Enterprise Server 11]]<br />
* [[AppSuite:Open-Xchange_Installation_Guide_for_RHEL6|Download and Installation Guide for RedHat Enterprise Linux 6]]<br />
<br />
You also should install and configure the OXtender for Business Mobility<br />
<br />
[[AppSuite:OXtender_for_Business_Mobility_Installation_Guide|Installation of the OXtender for Business Mobility]]<br />
<br />
Let your users connect to their data from other services like Facebook, Twitter or LinkedIn by configuring the "SocialOX"<br />
<br />
[[SocialOX|SocialOX-Configuration]]<br />
<br />
= Installation Steps depending on your environment - Instructions & Recommendations =<br />
<br />
'''The following components need to be implemented in your environment.'''<br />
<br />
<br />
{{OX_HE_Tutorial_CP}}<br />
<br />
<br />
{{OX_HE_Tutorial_HGP}}<br />
<br />
<br />
{{OX_HE_Tutorial_Plesk}}<br />
<br />
<br />
{{OX_HE_Tutorial_Auth}}<br />
<br />
== Connect Email System ==<br />
<br />
Every email system providing IMAP and SMTP can be used as backend to OX. Best experiences are made with the widespread Linux based IMAP servers [http://dovecot.org/ Dovecot], [http://www.cyrusimap.org/ Cyrus] or [http://www.courier-mta.org/imap/ Courier]. <br />
<br />
Other IMAP servers need to be tested thoroughly before going into production.<br />
<br />
There are several possibilities to implement the Email system:<br />
<br />
# You already have an email system available: Nothing needs to be done, it just needs to be configured<br />
# You use Plesk Panel: Nothing special needs to be done, everything you need is contained in the OXtender for Plesk<br />
# You want to setup a new Email system: It is recommended to use Dovecot, as this is very stable, fast, feature rich and easy to scale<br />
<br />
<br />
{{OX_HE_Tutorial_Dovecot}}<br />
<br />
<br />
{{AppSuite:OX_Tutorial_Next}}</div>Dennis Sieben