PA Provider Deployment Guide

Open-Xchange Odin Service Business Automation (former Parallels Automation) Deployment Guide

This guide describes the integration of Odin Business Automation with Open-Xchange. Please note that the Parallels service provider division has changed its name to Odin. This means that many of the products referred to on this page have also changed their name.

Terms and Abbreviations

APS

Application Packaging Standard

OBA

Odin Business Automation (former Parallels Business Automation PBA).

OSA

Odin Service Automation (former Parallels Operations Automation POA).

RST

Resource Type

RS

Resource

ST

Service Template

Context

In Open-Xchange, a Context is a container for one or more users. Usually one Context contains one domain..

Customer’s Workflow

Numbered list of steps the customer follows to use Open-Xchange.

1. Go to online store front and locate the Open-Xchange service.
2. Add the plan/subscription for the Open-Xchange Service to your cart.
3. On the checkout page review your order, accept the license agreement if any, then create a new customer account or login to an existing account to place your order.
4. Login to your Customer control Panel using the login credentials created during the initial purchase.
5. Select the appropriate subscription from the Subscription List on the Top of the Control Panel.
6. Go to Applications, you will find the subscribed Application on the dashboard, where the Open-Xchange APS Package is available.
7. Click on Open-Xchange APS application to start the installation.
8. Click on Create and enter user details.
9. Click next and confirm the fields are correct and press "Finish" to process.
10. After the application provisioning process is completed it will have the status Ready.
11. Click on Users to create some service users with access to Open-Xchange webmail.
12. An auto login (Entry point) link will be displayed on their control panel using which the customer can login to Open-Xchange.

Customer’s Lifecycle

Customers may make use of the service after acquiring a subscription from their Provider. In a typical setup, no resources are purchased up-front but are instead billed based on usage of mailboxes during consumption of these services.

Service Hierarchy Subscription Modification Options

• Main service
  • User Registration
• Sub-services
  • Entry point (Auto login) link to Open-Xchange Admin Account
  • Entry points to link to Open-Xchange Webmail accounts
• Odin (former Parallels) Open-Xchange customer subscription management
  • Through PBA storefront or subscription’s account details, user can purchase additional features or file storage
  • No other service upgrades or downgrades offered

Localization List

Supported translations of Open-Xchange as well as APS package translations of the customer interface are listed on the list of available translations

Changelog

7.2-26

• Fixed OX6 gui preferences merging

7.2-25

• Added all available timezones in OX App Suite and removed the static time zone designators from the entries

7.2-24

• Fixed debug logging
• Do not use the obsolete syncml setting anymore in combination with "Mobile devices support"

7.2-20

• Fixed displayname uniqueness check

7.2-19

• Fix loginMapping in getContextWithId and context Id in getContextData

7.2-18

• Ability to change admin user login

7.2-14

• since primary mail setting cannot be changed directly, setting has been removed
• eleminated more php warnings

7.2-9

• Added note to Horde migration setting that it does not work on Plesk
• Shortened the presentation summary
• reduced warnings in php code

7.2-6

• Increasing filestore_quota via resource now possible

7.2-5

• Fixed problem with POA versions > 5.5 and public contact folder
• Increased default upload size values of attachments and infostore
• Bugfix: Disabling a user now working

7.2-1

• Reseller Mode for Plesk
• Ready for Plesk 11.5 and above
• No support for Open-Xchange Version 6.20 anymore

7.0-10

• Fixed issue with creating resource types based on application service

7.0-7

• Bugfix when using Open-Xchange with Grizzly instead of AJP
• Added translations for various languages

7.0-4

• Public entry point added in top service
• Reporting mailbox password into user_password setting
• Context ID is not stored in file

7.0-2

• First version with support for latest Open-Xchange versions such as 6.22.2 and OX App Suite
• Added support for dutch language provisioning
• Due to compatibility reasons the account entry points have been reduced to one auto-login entry-point into Open-Xchange
• replaced deprecated php split with explode in configuration scripts
• added optional tag to optional settings in account service settings

Technical Integration Overview

This section contains an outline of how the integration of Open-Xchange and PA is performed and the list of Open-Xchange features that are supported within the integration package.

General Architecture

The following scheme represents the architecture of POA and Open-Xchange integration:

• Admin Level
  • Download the Open-Xchange APS from APS catalog
  • Install the APS package in POA
  • Follow all steps to create resource types
  • Fill all necessary Global settings
  • Follow all steps to create Service templates
  • Create plans in PBA
  • Publish it to PA Store front

• End user Level:
  • PA end user will come to Parallel automation Store front
  • Select respective plan from the storefront
  • Select the subscription period
  • Create a new user or use existing user account
  • Continue billing steps
  • Once billing is done the application will be provisioned under the user using values from the global settings
  • Login to customer account. Customer can see new subscription under available Open-Xchange subscription list
  • Entry points (auto-login) will be generated by the APS package once the package is successfully provisioned

Services Summary

• The end user has to add mail hosting to the domain that should be used with Open-Xchange.
• The Open-Xchange APS package allows the end user to create a Context in Open-Xchange.
• Once the Context has been created, the user can create webmail accounts for Open-Xchange using existing or new service users.
• Entry points will be created for each webmail account and for the Open-Xchange Admin account.
• Depending on the billing configuration (storage based, account or functionality based), the user can be billed.

Object Mapping

Odin Service Automation (former Parallels Automation) subscription corresponds to Context in Open-Xchange and Odin Service Automation end users correspond to users in Open-Xchange.

Requirements

The APS Package requires POA 5.0 or higher, Plesk 11.5 or higher and Open-Xchange 6.22.3 or higher / OX App Suite 7.2.1 or higher. Hence updating from e.g. 6.20.7 to 6.22.0 needs a further update to a required version as 6.22.0 doesn't work with APS package at all because 6.22.0 doesn't provide a proper authentication service which works with Odin.

Known issues

• Controlling module access combination names of created contexts results into "null". The reason is, that the aps package removes the editPassword right and thus, no existing access combination name exists per default, that match the individual settings.

Download

APS package

Download the APS package from the APS catalog: Open-Xchange

Open-Xchange

Simply follow the "Hosting Edition deployment tutorials" at Main_Page_HESE#quickinstall to install Open-Xchange Hosting Edition on your favorite Linux distribution, but make sure you install the packages below instead of the default OX meta/packages provided in the manual, because PA integration needs a different set of software:

Note: Stop before step "Creating contexts and users " - this is not necessary since all administration of contexts and users will be handled via PA.

Please install following packages on the OX server. These are mandatory for the PA  integration:

open­-xchange­-parallels 
open­-xchange­-parallels­-gui 
open­-xchange­-spamhandler­-spamassassin 
open­-xchange­-admin­-soap 

or

open-xchange-meta-parallels 

Important:

Make sure that you don't have any other „spamhandler“ package installed like „open-xchange-spamhandler-default“. Also make sure, that you dont have any other OX authentication package installed like „open-xchange-authentication-database“. Additionally, don't install following packages, since they are not needed for POA installation:

open-xchange-admin-plugin-contextrestore, open-xchange-log4j, open-xchange-passwordchange-database, open-xchange-passwordchange-servlet

If already installed, please uninstall first!

These packages contain POA specific plugins for authentication, branding and advanced antispam cababilities. After you installed these packages via your favorite package manager like apt or yum, please restart the open-xchange server. To verify that the plugins are correctly loaded, please execute the command „listbundles“ which is located in /opt/open-xchange/sbin“. It should return a list with all „ACTIVE“ bundles.

If the bundle „com.openexchange.custom.parallels“ is not set to „ACTIVE“, please have a look at all OX logfiles located under „/var/log/open-xchange“ and watch out for error messages.

Installation of the Connector for Business Mobility

If you plan to sell Open-Xchange Business Mobility function (synchronisation with mobile phones) in combination with PA, you should also follow the official installation guide, which can be found also on the OXpedia website:

Connector for Business Mobility Installation

Open-Xchange Configuration

SOAP

The PA system must be able to access at least one Open-Xchange server via SOAP. This can be configured via apache configuration. When you followed our guides, that will be in the file /etc/apache2/conf.d/proxy_http.conf on Debian or /etc/httpd/conf.d/proxy_http.conf in Redhat based systems. It might look like this

<Location /webservices>
   # restrict access to the soap provisioning API
   Order Deny,Allow
   Deny from all
   Allow from 127.0.0.1 192.168 172.16.1.2
</Location>

which would allow access to the SOAP provisioning on the network 192.168 and on the single hosts 127.0.0.1 and 172.16.1.2 When the POA system is not listed here, you will see Forbidden messages in POA task log.

Configuration of POA specific OX plugins

In /opt/open-xchange/etc/sessiond.properties set

com.openexchange.sessiond.autologin=true

If not, users will get the message The action "store" is disabled due to server configuration when they directly access Open-Xchange via POA.

In /opt/open-xchange/etc/login.properties add the new setting

com.openexchange.login.formLoginWithoutAuthId=true

In /opt/open-xchange/etc/plugin/hosting.properties set

CHECK_CONTEXT_LOGIN_MAPPING_REGEXP=[$%:\\.+a-zA-Z0-9@_\\/\\|-]

In /opt/open-xchange/etc/AdminUser.properties set

PRIMARY_MAIL_UNCHANGEABLE=false

a) To enable the OX-POA antispam functionality you must first edit file „/opt/open-xchange/etc/imap.properties“ and set property „com.openexchange.imap.spamHandler“ to value „SpamAssassin“.

# Define the registration name of the appropriate spam handler to use
com.openexchange.imap.spamHandler=SpamAssassin

Next you have to edit file „/opt/open-xchange/etc/spamassassin.properties“ and set property „com.openexchange.spamhandler.spamassassin.spamd“ to value „true“.

# Choose if a mail should be send to spamd afterwards
com.openexchange.spamhandler.spamassassin.spamd=true


INFO:


If the Spamassassin proxy service runs on a different port than „3100“.

Please edit file:

"/opt/open-xchange/etc/parallels.properties"

and set property

"com.openexchange.custom.parallels.antispam.xmlrpc.port" to your custom port.

Make sure that the OX HOST IPs are added to "/etc/mail/spamassassin/allowed_ips" on the POA antispam/mail server. Else OX can not connect to POA spamassasin to learn new mails and you will get "connection reset" errors in open-xchange logfile.

2a) To configure POA antispam lists management via OX UI through POA-OpenAPI, you have to modify "/opt/open-xchange/etc/parallels.properties" and should adjust following parameters:

#
## OpenAPI properties for managing Black&White Lists via OX GUI
#
# This property defines the URL to the HTTP OpenAPI interface of POA
com.openexchange.custom.parallels.openapi.interface_url=http://<coreserver>:<port>/

#
# This property defines if OpenAPI calls should be made with http basic auth
com.openexchange.custom.parallels.openapi.auth_enabled=false

#
# This property defines OpenAPI http basic auth credentials auth id
com.openexchange.custom.parallels.openapi.auth_id=openapi_user_id

#
# This property defines OpenAPI http basic auth credentials auth password
com.openexchange.custom.parallels.openapi.auth_password=openapi_password

#
# The property defines the mount point of the OX OpenAPI servlet implementation.
# Typically, no need to change it.
com.openexchange.custom.parallels.openapi_servlet=/ajax/parallels/openapi

b) To enable correct branding for POA resellers and their customers, you have to define a „fallback“ FQDN under which the OX installation is reachable under the default skin/theme via http/https. 
To achieve this, please edit file „/opt/open-change/etc/parallels.properties“ and set property „com.openexchange.custom.parallels.branding.fallbackurl“ to the approciate value of your OX installation.

# THIS property below must only contain FQDN to OX GUI
# like webmail.system.com/ox6
com.openexchange.custom.parallels.branding.fallbackurl=ox.aps.sw.ru

c)To enable correctly generated direct links when customer/context is branded you have to edit file „/opt/open-xchange/etc/notification.properties“ and set property „object_link“ to value „http://[hostname]/#m=[module]&i=[object]&f=[folder]“

object_link=http://[hostname]/#m=[module]&i=[object]&f=[folder]

d) To support IDN Domains you also have to switch off username validation. To achieve this, please modify file "/opt/open-xchange/etc/AdminUser.properties" and update corresponding property:

CHECK_USER_UID_FOR_NOT_ALLOWED_CHARS=false

After you have edited all these properties, please restart „open-xchange" and apache service via init scripts. Now you need to write down the „oxadminmaster“ username and its password which you set up during installation of the normal OX system. Then you should give these credentials and the OX IP/Hostname to the POA specialist. He will enter this infos in the POA environment.

POA Deployment

Creating 'External Provisioning' Attribute

Create the External Provisioning Attribute.

Deploying POA Linux Mail Hosting Module

Deploy the POA Linux Mail Hosting Module using the instructions provided in the POA Linux Mail Hosting Deployment Guide.

1. The Linux Mail Hosting Module supports the CourierIMAP and Dovecot POP/IMAP Services (the last one is recommended to work with Open-Xchange).
2. If you plan to provide to customers the ability to manage the Sieve mail filtering rules through Open-Xchange Control Panel, install the latest version of the dovecot (type: other) POA Package instead of the CourierIMAP (type: other) POA Package. If the existing installation of Linux Mail Hosting Module is used, perform the migration from Courier-IMAP Service to Dovecot POP/IMAP Service. Instructions how to perform the migration are provided in the POA Linux Mail Hosting Deployment Guide, the Deploying Linux Mail Hosting > Migrating from Courier-IMAP Service to Dovecot Service section.
3. If you plan to provide to customers the ability to manage the Sieve mail filtering rules through Open-Xchange Control Panel and Clustered QMail Service is used as SMTP/IMAP server for Open-Xchange, add the load balancing rule for TCP port 2000 on Load Balancer. See the POA Linux Mail Hosting Deployment Guide, the Deploying Linux Mail Hosting > Deploying Clustered Qmail Service > Creating Load Balancer section for details.
4. It is not required to deploy the IMP and AtMail Webmail Services. 5. The SpamAssassin and DrWeb Services are optional.

Create the Resource Types, which are required for Linux Mail Hosting provisioning

• CQMail Hosting Resource Type. Use the instructions provided in POA Provider's Guide, the Mail Hosting in POA > Creating 'CQMail Hosting' Resource Type section.
• SpamAssassin Protection. Create the SpamAssassin Protection Resource Type on the basis of the Antispam for mailboxes Resource Class. Instructions on how to do this, are provided in Provider's Guide, the Managing Service Templates > Creating Resource Type section.
• Traffic. Create the Traffic Resource Type on the basis of the Traffic Resource Class. Instructions on how to do this, are provided in Provider's Guide, the Managing Service Templates > Creating Resource Type section.
• Diskspace. Create the Diskspace Resource Type on the basis of the Diskspace Resource Class. Instructions on how to do this, are provided in Provider's Guide, the Managing Service Templates > Creating Resource Type section.

Mark the host where clustered-qmail service is installed as Ready To Provide.

Note: Already existing in POA Linux Mail Hosting Module can also be used for deployment.

Preparing Provisioning Gateway Host

• Install php-cgi
• The Application management scripts are contained in the Application package. POA installs Application the management scripts on this host.
• The management scripts provision the Open-Xchange server via http using the SOAP protocol and thus. the Open-Xchange server must be accessible from the provisioning host using these protocols.
• Assign the External Provisioning Attribute to the Provisioning Gateway Host.
• Mark the Provisioning Gateway Host as Ready To Provide.

POA Configuration

Import the Application

Deploy the application from the APS catalogue.

APS Package Resource configuration

• Click on Add New Resource Type in Top > Service Director > Provisioning Manager > Resource Types.
• Click on the Application Resource class
• Set a name and description
• Select Open-Xchange from the list of applications
• Fill the Global application settings (see below)
• Set the "External Provisioning" attribute

Global application settings

Open-Xchange installation host

DNS hostname or ip address of the Open-Xchange provisioning host (will be accessed via SOAP)

Open-Xchange public site URL

The URL on how to access Open-Xchange Webmail

Product path to access Open-Xchange

Chose the product path depending on your configuration. On OX App Suite, this is /appsuite/ per default, on OX6, it is /ox6/. Note that the trailing "/" is mandatory.

Open-Xchange Autologin identifier

Chose either OX App Suite or OX6

Master Administrator Login

OX provisioning account with rights to create contexts

Master Administrator Password

Password of provisioning account

Open-Xchange administrator access level

The access level of the context admin account. Check /opt/open-xchange/etc/ModuleAccessDefinitions.properties for a list of possible values. Should be a permissive value like groupware_premium in order for the admin to be able to manage all features.

Open-Xchange anti-spam protection interface

It defines whether the spam reporting functionality is enabled. If it is enabled, the Open-Xchange context user is able to mark messages as spam/not spam. Make it enabled. Note that this does not yet work in OX App Suite.

Public contacts folder

Public folder to place contacts of non Open-Xchange service users into. Not to confuse with the standard public contacts folder in Open-Xchange where every OX mail account is listed.

Enable data migration from Horde

Enable if you want to migrate data from an existing Horde installation.

URL to source Horde

Provide URL to Horde Webmail. Will be used only if data migration is enabled in previous setting.

Service with Connector for Business Mobility

Choose "Webmail Account" if you plan to have mobility per default in a webmail account.

Reseller mode

This should be Off in most cases when in use with POA. Makes sense in Plesk deployment, see Plesk_Integration Note: This setting must not be changed after contexts have been already created.

Debug mode

Should be Off per default.

Application service "Open-Xchange context"

Open-Xchange context wide filestore quota (in MB)

Specify the overall size that can be used to store files in the Open-Xchange context

Default time zone

Specify the default timezone for new users

Branding scheme name

The name of the Open-Xchange theme which is applied to the context user. If the parameter is not specified, the default Open-Xchange theme is used.

Application service "Webmail Account"

Open-Xchange module access level for Enduser

Specify the access level of a webmail user. Check /opt/open-xchange/etc/ModuleAccessDefinitions.properties for a list of possible values.

Maximum size of all attachments in one message (in bytes)

Specify "0" for unlimited

Maximum size of one attachment, maximum size of one InfoStore item (in bytes)

Specify "0" for unlimited

Note: For an overview of the different supported access levels, see OX_Permission_Level.

OX App Suite or OX 6

Depending on whether you plan to integrate OX App Suite or OX 6, you have to select the correct identifier.

Running OX App Suite and OX 6 in parallel

On a parallel setup of OX App Suite and OX6 you may want to access both from you POA. This can be achieved in creating two resource types in the POA Provisioning Manager. One for OX App Suite and one for OX 6. In the Product path setting, you can either specify the path to OX App Suite or to OX6

Note: Do not configure an automatic redirect/url rewrite in this case.

Create some Resource Types based on Application Service

Now lets create some Resource Types based on Application Service to have something to up-sell.

Webmail, PIM and Groupware Resource Types

• Click on Add New Resource Type in Top > Service Director > Provisioning Manager > Resource Types
• Chose Application Service
• Fill out name and description

• Select Open-Xchange Application
• Select Webmail Account

• Set Priotity to 1
• Enter webmail as access level

• Now do the same for PIM and Groupware.
  • module access level for PIM is pim
  • module access level for Groupware is groupware
  • you can chose better maximum sizes for pim and groupware if you want

Create a Mobility Resource Type based on Application Service

• Click on Add New Resource Type in Top > Service Director > Provisioning Manager > Resource Types
• Chose Application Resource
• Fill out name and description
• Select Open-Xchange Application
• Select Mobile devices support
• Leave Priority empty

Create a Resource Type based on Application Resource

• Click on Add New Resource Type in Top > Service Director > Provisioning Manager > Resource Types
• Chose Application Resource
• Fill out name and description
• Select Open-Xchange Application
• Click on Disk space used by Open-Xchange context infostore files

At the end, you should have six Resource Types:

Optionally: Remove Mobile devices support from Webmail, PIM and Groupware Resource Types

If you don't want to sell Mobile devices support as an extra service, e.g. when it is already part of one of the access levels used in the Resource Types, go to the global settings and choose "Webmail Account" instead of "Mobile devices support".

Create a Service Template

• Click on Add New Service Template in Top > Service Director > Provisioning Manager > Service Templates
• Fill out name and description
• Select Mail Hosting (based on qmail).

• Select a proper Traffic and Diskspace Resource Type

• Now add further Resource Types to the new Service Template

• Find an add all four Resource Types that have been created earlier

• Do not use the Unlimited value for the Open-Xchange Context Diskspace resource. Use the limited values that are large enough. For example: 2 GB, 4 GB, and etc.

• Finally, you have to activate the Service Template in the General tab

Updating from 6.20 to 6.22 or newer

Open-Xchange 6.22 uses a different mechanism to let users single sign on from POA to OX. In 6.20 and earlier, a mechanism called EasyLogin was used. Since 6.22, a new mechanism called Formlogin has been introduced and EasyLogin is no longer available.

Since support for easylogin has been removed also in the Open-Xchange APS package, you can use an older version as an intermediate solution if you plan to upgrade now. Version 7.0-10 was the last one supporting both, EasyLogin and Formlogin.

https://apscatalog.com/1.2/Open-Xchange%20Inc./Open-Xchange/7.0-10.aps?arch=undefined&packager=Open-Xchange&os=undefined&platform=undefined

Support for features like OX Text and OX Guard

The Open-Xchange APS1.2 package does not directly support the new way to control latest features in Open-Xchange which are controlled using the ConfigCascade and Capabilities. There is, however, a way to use them using contextSets.

Some of the old style features of Open-Xchange like webdavxml or syncml are no longer needed and thus they can be used to tie different capabilities to them.

Note: Using the syncml feature only works with Open-Xchange APS package 7.2-24 or later since that flag was still used for the Mobile Devices Support in version before. Mobile Devices Support, however, is nowadays reflected only through the activesync feature.

Let's say you want to sell a package containing OX Guard and a package OX Text to your customers using PA. The following example will use the syncml feature to tie OX Guard to it and the webdavxml feature for OX Text.

First thing to do is to create two module access combination names within /opt/open-xchange/etc/ModuleAccessDefinitions.properties for each of it:

oxguard=syncml,webmail,calendar,contacts,infostore,tasks,webdav,ical,vcard,usm,olox20,activesync,readcreatesharedfolders,delegatetask,editpublicfolders,editgroup,editresource,editpassword,publicfoldereditable,collectemailaddresses,multiplemailaccounts,subscription,publication

oxoffice=webdavxml,webmail,calendar,contacts,infostore,tasks,webdav,ical,vcard,usm,olox20,activesync,readcreatesharedfolders,delegatetask,editpublicfolders,editgroup,editresource,editpassword,publicfoldereditable,collectemailaddresses,multiplemailaccounts,subscription,publication

these are based on the all combination, but of course you can modify it if you want. Essential is, that we add syncml to the oxguard and webdavxml to the oxoffice only.

Next we create a file /opt/open-xchange/etc/contextSets/packages.yml

oxguard:
   withTags: ucSyncML
   com.openexchange.capability.guard: true
   com.openexchange.capability.guard-mail: true
   com.openexchange.capability.guard-drive: true

oxoffice:
   withTags: ucWebDAVXML
   com.openexchange.capability.text: true
   com.openexchange.capability.spreadsheet: true

were we tie the capabilities to enable each of the features to the corresponding tag.

Please, make sure to create the indentation as shown above by using spaces and not tabs as yml files are very particular about the formatting.

You also need to define the capabilities used in the file above in the properties files and set them to false:

/opt/open-xchange/etc/guard.properties:

com.openexchange.capability.guard=false
com.openexchange.capability.guard-mail=false
com.openexchange.capability.guard-drive=false

/opt/open-xchange/etc/documents.properties:

com.openexchange.capability.text=false
com.openexchange.capability.spreadsheet=false

Just for the completeness, find below the name of existing tags that correspond to the names in the file /opt/open-xchange/etc/ModuleAccessDefinitions.properties

• ucWebMail
• ucCalendar
• ucContacts
• ucTasks
• ucInfostore
• ucWebDAVXML
• ucWebDAV
• ucICal
• ucVCard
• ucSyncML
• ucFullPublicFolderAccess
• ucFullSharedFolderAccess
• ucDelegateTasks
• ucEditGroup
• ucEditResource
• ucEditPassword
• ucCollectEMailAddresses
• ucMultipleMailAccounts
• ucSubscription
• ucPublication
• ucActiveSync
• ucUSM
• ucOLOX20
• ucDeniedPortal
• ucCalDAV
• ucCardDAV

Now once you have done that, and of course you have already installed and configured OX Guard and OX Text accordingly, you can create new resources based on the Application Service "Webmail Account", e.g. like in the screenshot below where we define an Application Service Resource for the OX Guard offering.

The same can be done using the defined oxoffice access combination name.