View source for Open-Xchange cPanel Installation

= Install Open-Xchange on WHM/cPanel =

== Requirements ==

Connector for cPanel requires to have WHM versions from '''11.32 to 11.38''' installed running on RHEL 5,6 or CentOS 5,6.
It supports Open-Xchange versions 6.20 and newer. This guide, however, describes how to setup Open-Xchange
Server 6.22 and above.

'''Important: Do not update to newer versions of cPanel then mentioned here.''' You might want to turn autoupdates of in
setting 

 UPDATES=manual

in <tt>/etc/cpupdate.conf</tt>

== Changelog ==

=== 1.1.0-rev4 ===

* Fixed Addon Domain handling (login to Open-Xchange was not working for email accounts in Addon Domains)

=== 1.1.0-rev3 ===

* Support for CentOS6/RHEL6
* Support for OX App Suite

== Mode of operation ==

It is recommended to run Open-Xchange on one or more separate machines. See the "''Hosting Edition deployment tutorials''" at 

; Open-Xchange Server 6 : [[Main_Page_HESE#quickinstall]].
; OX App Suite : [[AppSuite:Main_Page_AppSuite#quickinstall]]

The connection between cPanel and Open-Xchange is done via some cPanel/WHM hooks and UI plugins using SOAP as communication channel. That means that SOAP must be enabled on Open-Xchange.

[[Image:CPOX.png]]

Once the package open-xchange-cpanel is installed on the cPanel/WHM system, every cPanel user created within WHM will be created as an admin account and context in Open-Xchange.
In addition, there's a single program to create all existing cPanel Accounts in Open-Xchange.

== Availability ==

Connector for cPanel is available with a valid Open-Xchange Hosting Edition license. To get pricing information that meets your individual requirements, [http://www.open-xchange.com/home.html?lburl=www.open-xchange.com/index.php?id=397&iframe=1&iframe=1 please contact Open-Xchange]

== Known issues ==

{{CPanelKnownIssues}}

==Release Notes==

To download the Release Notes, follow this:
[http://software.open-xchange.com/components/cPanel/stable/ Download] 

== Install and prepare Open-Xchange ==

Follow one of the [http://oxpedia.org/index.php?title=Main_Page_HESE Open-Xchange installation guides] to install Open-Xchange and either just install the packages

'''On OX6 with backend versions < 7.2.2''':
 open-xchange-meta-cpanel

'''On OX6 with backend versions >= 7.2.2''':
 open-xchange-meta-cpanel open-xchange-meta-backend-ox6 open-xchange-meta-ui-ox6

'''On OX App Suite version >= 7.2.2 (older versions not supported):'''
 open-xchange-meta-cpanel open-xchange-meta-backend-appsuite open-xchange-meta-ui-appsuite

or take care of '''the following exceptions''':

* Do not install the package <tt>open-xchange-mailfilter</tt>. cPanel does not support SIEVE at the moment.
* Install the package <tt>open-xchange-admin-soap-reseller</tt>
* Instead of <tt>open-xchange-authentication-database</tt>, install the package <tt>open-xchange-authentication-imap</tt>

'''Important:'''

* Do '''NOT''' create a context, just follow the installation guide up to the database registration
* Add the following argument to initconfigdb: <tt>--addon-sql "reseller.sql autocid.sql"</tt>

== Preparation ==

* run the command
 $ /opt/open-xchange/sbin/initrestrictions -A oxadminmaster -P secret
once you've finished the open-xchange installation
* On OX6 take care to install the packages <tt>open-xchange-gui-wizard-plugin</tt> <tt>open-xchange-gui-wizard-plugin-gui</tt>. The wizard must be used to enforce the user to provide a real valid displayname.
* On OX6 edit file <tt>/opt/open-xchange/etc/settings/open-xchange-gui-wizard-plugin.properties</tt> and set
 ui/wizard/firstrunmode=true
* edit file <tt>/opt/open-xchange/etc/imapauth.properties</tt> and set
 USE_MULTIPLE=true
* edit file <tt>/opt/open-xchange/etc/mail.properties</tt> and set
 com.openexchange.mail.adminMailLoginEnabled=true
* edit file <tt>/opt/open-xchange/etc/sessiond.properties</tt> and set
 com.openexchange.sessiond.autologin=true
* edit file <tt>/opt/open-xchange/etc/AdminUser.properties</tt> and set
 PRIMARY_MAIL_UNCHANGEABLE=false
* allow access from the cPanel server, edit <tt>/etc/httpd/conf.d/proxy_ajp.conf</tt>

 <Location /servlet/axis2/services>
    # restrict access to the soap provisioning API
    Order Deny,Allow
    Deny from all
    Allow from 127.0.0.1
    Allow from <your cpanel server ip>
    # you might add more ip addresses / networks here
    # Allow from 192.168 10 172.16
 </Location>
 [...]

== Install and prepare WHM/cPanel on CentOS ==

'''Note:''' Choose either CentOS5,6 or RHEL5,6. Nothing else is supported to integrate Open-Xchange with cPanel.

'''Important: If you have existing cpanel plugins that use <tt>/script</tt> hooks (or <tt>/usr/local/cpanel/script</tt>), as well as /usr/local/cpanel/hooks, take care to make a backup of these files because they will be replaced by the <tt>open-xchange-cpanel</tt> rpm'''

* Follow the installation guide http://docs.cpanel.net/twiki/bin/view/AllDocumentation/InstallationGuide/Quick-StartInstallationGuide
* run <tt>/scripts/upcp</tt>
* run <tt>/scripts/perlinstaller SOAP::Lite</tt>
'''NOTE: This can take very long and it might look like it is hanging at'''
 We are about to install SOAP::Lite and for your convenience will provide
 you with list of modules and prerequisites, so you'll be able to choose
 only modules you need for your configuration.
 
 XMLRPC::Lite, UDDI::Lite, and XML::Parser::Lite are included by default.
 Installed transports can be used for both SOAP::Lite and XMLRPC::Lite.
 
 Press <enter> to see the detailed list.  

Just be patient and wait for it to finish.

* add the repository http://software.open-xchange.com/components/cPanel/stable/RHEL6 to your yum configuration

'''VERY IMPORTANT:'''
Due to the inability of yum to correctly handle the x86_64 architecture, it is important to add the line

 exclude=*.i386

to your yum repo configuration (see below).
Check http://wiki.centos.org/FAQ/General#head-357346ff0bf7c14b0849c3bcce39677aaca528e9 for details.

=== yum repo config on i386 ===

 $ vi /etc/yum.repos.d/oxintegration.repo
 [oxcpintegration]
 name=Open-Xchange cPanel
 baseurl=http://LDBACCOUNT:LDBPASSWORD@software.open-xchange.com/components/cPanel/stable/RHEL6
 gpgkey=http://software.open-xchange.com/oxbuildkey.pub
 enabled=1
 gpgcheck=1
 metadata_expire=0m

=== yum repo config on x86_64 ===

 $ vi /etc/yum.repos.d/oxintegration.repo
 [oxcpintegration]
 name=Open-Xchange cPanel
 baseurl=http://LDBACCOUNT:LDBPASSWORD@software.open-xchange.com/components/cPanel/stable/RHEL6
 gpgkey=http://software.open-xchange.com/oxbuildkey.pub
 enabled=1
 gpgcheck=1
 metadata_expire=0m
 #IMPORTANT!!!!!
 exclude=*.i386


* install the package <tt>open-xchange-cpanel</tt>
 $ yum install open-xchange-cpanel
* run the installer (-h for help):
 $ /usr/local/cpanel/bin/oxcpanelinstall --oxurl http://ox.example.com --oxadmin-password oxadminmasterpassword

Now your Open-Xchange server is integrated with your cPanel installation.

To check the connection, run

 $ /usr/local/cpanel/bin/oxcpanelenable -c

This program can also be used to enable all existing cPanel users in OX.
Run
 $ /usr/local/cpanel/bin/oxcpanelenable -h
for more information.

== Create all cPanel Accounts in Open-Xchange ==

Like mentioned before, you must now create accounts in Open-Xchange for all your
existing cPanel accounts. This will not happen automatically. New accounts created in WHM, however, will automatically created in Open-Xchange.

To create an ox account per cPanel account you can either run

 $ /usr/local/cpanel/bin/oxcpanelenable -e

or in the Open-Xchange WHM plugin click on every single cPanel Account and enable it.

== Debugging ==

* run the command 
 $ sudo /usr/local/cpanel/bin/oxcpanelenable -c
to check Open-Xchange connection before doing anything else. It must output
'''connection check successfull'''
* All errors happening during cPanel account creation and mail account creation are logged into the files <tt>/usr/local/cpanel/logs/open-xchange_log</tt> and <tt>/usr/local/cpanel/logs/error_log</tt>. If something does not work, check these logs first!
* <tt>/usr/local/cpanel/bin/oxcpanelinstall</tt> creates a debug output file with every execution, check its output, e.g.:
 $ /usr/local/cpanel/bin/oxcpanelinstall --oxurl http://myox.example.com --oxadmin-password secret
 running installer, please wait. Debugoutput is placed into file /tmp/cpoxinst3542.out
* do NOT disable authentication in <tt>/opt/open-xchange/etc/AdminDaemon.properties</tt> because this will mess up authentication using the Connector for cPanel, see [[Reseller_Bundle#Setup_and_Configuration]] for more information.

When you're seeing this error in the logfile(s):

 [addon_open-xchange] ERROR: Incorrect parameter at /usr/local/cpanel/3rdparty/perl/514/lib64/perl5/cpanel_lib/SOAP/Lite.pm line 1993.
 at /usr/local/cpanel//Cpanel/OX/SOAP.pm line 26

You did not run

 $ /scripts/perlinstaller SOAP::Lite

prior to installing the <tt>open-xchange-cpanel</tt> integration package.

= WHM OX Plugin Usage =

To create Open-Xchange accounts, nothing else is required than to create cPanel accounts
as usual. Due to the design of the WHM plugin mechanism, however, it is not possible to
indicate any errors that might happen when creating the account in Open-Xchange fails.

You can easily check, however, if the Open-Xchange account creation failed when you open
the Open-Xchange plugin which can be found in the left menu in WHM almost on the bottom.

[[File:whm-ox-failed.png]]

Failed attempts to create an ox accounts can be seen there because in that case, the account
is not enabled.
In such a case you need to Terminate that account and create it again after you fixed the reason for the failed attempt. Check the logs for errors.

[[File:whm-ox-enable.png]]

In addition you will find all relevant error messages in <tt>/usr/local/cpanel/logs/open-xchange_log</tt> and <tt>/usr/local/cpanel/logs/error_log</tt>.

= cPanel OX Plugin Usage =

To create email accounts in Open-Xchange, nothing else is required than to create email accounts
in cPanel. Due to the design of the cPanel plugin mechanism, however, it is not possible to
indicate any errors that might happen when creating the account in Open-Xchange fails.

To check whether the email account creation fails, just open the Open-Xchange plugin and check
if the recently created email account(s) appear in the list. If not, contact your hosting provider or, if you are the owner of the machine, you will find all relevant error messages in <tt>/usr/local/cpanel/logs/open-xchange_log</tt> and <tt>/usr/local/cpanel/logs/error_log</tt>.

[[File:cpanel-account-list.png]]

= Running multiple WHM/cPanel instances with a single Open-Xchange instance (cluster) =

'''Starting with version 1.0.0 Rev2''' it is possible to run multiple WHM/cPanel instances with a single Open-Xchange (cluster) installation. This, however, requires some extra management which is not part of the <tt>open-xchange-cpanel</tt> package nor is there any other ready to use ui for that.

The setup of the cPanel server and Connector is the same as described in the [[Open-Xchange_cPanel_Installation#Install_and_prepare_WHM.2FcPanel_on_CentOS|installation section]].
The same applies to the installation of the Open-Xchange server. Once the Open-Xchange server is installed, however, you need to create a subadmin account per WHM/cPanel server. These subadmins must be able to create further subadmin accounts (one per cPanel account).

 $ /opt/open-xchange/sbin/createadmin -A oxadminmaster -P secret -u cpanelmaster1 -d "cPanel Superadmin 1" -p secret -a Subadmin.CanCreateSubadmin=true

 $ /opt/open-xchange/sbin/createadmin -A oxadminmaster -P secret -u cpanelmaster2 -d "cPanel Superadmin 2" -p secret -a Subadmin.CanCreateSubadmin=true

and so on.
You can also restrict the maximum number of subadmins a subadmin can create, see [[Reseller_Bundle#Open-Xchange_Reseller_package|Reseller Bundle]] description for further details.

 $ /opt/open-xchange/sbin/listadmin -A oxadminmaster -P secret
 Id Name          Displayname         Parent Restrictions
 96 cpanelmaster1 cPanel Superadmin 1 0      Subadmin.CanCreateSubadmin=true
 97 cpanelmaster2 cPanel Superadmin 2 0      Subadmin.CanCreateSubadmin=true

Now on each WHM/cPanel installation, instead of using the oxadminmaster account when running the <tt>oxcpanelinstaller</tt>, specify the corresponding cpanel supadmin, e.g.

 $ /usr/local/cpanel/bin/oxcpanelinstall --oxurl http://ox.example.com --oxadmin-name cpanelmaster1 --oxadmin-password secret

and so on.