Connector for cPanel requires to have WHM version 11.48 installed running on RHEL 5,6 or CentOS 5,6. It supports Open-Xchange versions 6.22 and newer. In general, cPanel versions that are no longer supported by cPanel itself, are not supported.
Note that version 11.46 would also work but with some patchlevel it introduced a bug where the Open-Xchange icon is no longer displayed in the cPanel UI.
Important: Do not update to newer versions of cPanel than mentioned here. You might want to turn autoupdates off in setting
It is recommended to run Open-Xchange on one or more separate machines. See the "Hosting Edition deployment tutorials" at
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.
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.
Connector for cPanel is available with a valid Open-Xchange Hosting Edition license. To get pricing information that meets your individual requirements, please contact Open-Xchange
To download the Release Notes, follow this: Download
Follow one of the installation guides listed in here to install Open-Xchange and either just install the packages
open-xchange-meta-cpanel open-xchange-meta-backend-ox6 open-xchange-meta-ui-ox6
On OX App Suite
open-xchange-meta-cpanel open-xchange-meta-backend-appsuite open-xchange-meta-ui-appsuite
or take care of the following exceptions:
$ /opt/open-xchange/sbin/initrestrictions -A oxadminmaster -P secret
once you've finished the open-xchange installation
<Location /webservices> # 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>
Important: It is required to NOT set MASTER_AUTHENTICATION_DISABLED=true or CONTEXT_AUTHENTICATION_DISABLED=true in /opt/open-xchange/etc/AdminDaemon.properties
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 /script hooks (or /usr/local/cpanel/script), as well as /usr/local/cpanel/hooks, take care to make a backup of these files because they will be replaced by the open-xchange-cpanel rpm
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.
VERY IMPORTANT: Due to the inability of yum to correctly handle the x86_64 architecture, it is important to add the line
to your yum repo configuration (see below). Check http://wiki.centos.org/FAQ/General#head-357346ff0bf7c14b0849c3bcce39677aaca528e9 for details.
$ vi /etc/yum.repos.d/oxintegration.repo [oxcpintegration] name=Open-Xchange cPanel baseurl=https://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
$ vi /etc/yum.repos.d/oxintegration.repo [oxcpintegration] name=Open-Xchange cPanel baseurl=https://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
$ yum install open-xchange-cpanel
$ /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.
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.
$ /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
Creation of Accounts in Open-Xchange does not work? Please check the following:
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
run the command
$ sudo /usr/local/cpanel/bin/manage_hooks list | grep OX
it must output
hook: OX::Hooks::unpark_domain hook: OX::Hooks::addpop hook: OX::Hooks::del_addon_domain hook: OX::Hooks::park_domain hook: OX::Hooks::delpop hook: OX::Hooks::add_addon_domain hook: OX::Hooks::postrestore hook: OX::Hooks::delete_ox_account hook: OX::Hooks::create_ox_account hook: OX::Hooks::park_domain hook: OX::Hooks::modify_ox_account hook: OX::Hooks::unpark_domain
If it doesn't, run
$ sudo /usr/local/cpanel/bin/manage_hooks del module OX::Hooks
to clean up all OX Hooks, if there are any, and then run
$ sudo /usr/local/cpanel/bin/manage_hooks add module OX::Hooks
Added hook for Whostmgr::Accounts::Create to hooks registry Added hook for Whostmgr::Accounts::Remove to hooks registry Added hook for Whostmgr::Accounts::Modify to hooks registry Added hook for PkgAcct::Restore to hooks registry Added hook for Cpanel::Api2::AddonDomain::addaddondomain to hooks registry Added hook for Cpanel::Api2::AddonDomain::deladdondomain to hooks registry Added hook for Cpanel::Api1::Park::park to hooks registry Added hook for Cpanel::Api1::Park::unpark to hooks registry Added hook for Whostmgr::Domain::park to hooks registry Added hook for Whostmgr::Domain::unpark to hooks registry Added hook for Cpanel::Api2::Email::addpop to hooks registry Added hook for Cpanel::Api2::Email::delpop to hooks registry
Check for known issues, e.g. you might been hit by a bug in SOAP::Lite.
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.
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.
In addition you will find all relevant error messages in /usr/local/cpanel/logs/open-xchange_log and /usr/local/cpanel/logs/error_log.
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 /usr/local/cpanel/logs/open-xchange_log and /usr/local/cpanel/logs/error_log.
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 open-xchange-cpanel 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 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 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 oxcpanelinstaller, 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.
Beginning with the release 1.1.2, copying accounts between cPanel servers is now supported by the cPanel connector. In order to use that feature, however, it is required to understand and agree how it is going to work.
In general, Open-Xchange provisioning requires to have the correct and sufficient credentials in order to operate. The cPanel connector per default stores these credentials in a local directory /var/cpanel/open-xchange/subadmin/<CPANELACCOUNT> which can only be accessed by the root account. Unfortunately when you transfer an account having Open-Xchange to a different server, this directory is not transferred and thus on the destination cPanel server, settings cannot be updated (such as imap and smtp server hostname which is now on the new server).
In order to solve this problem, version 1.1.2 of the connector now optionally saves the provisioning credentials within the cPanel accounts cpuser data (internal cPanel storage). These settings are transferred with a cPanel backup.
To store credentials in the cpuser data, you can either run the installer with the additional option "-C" or manually add
Changing this setting does NOT automatically update all existing accounts. It just applies for new users. To migrate existing credentials between local storage or cpuser storage, the command /usr/local/cpanel/bin/oxcpanelenable must be used.
Lets say your existing cPanel integration already has some users and you want to take benefit of the new account transfer feature. All you have to do is to
After you've done that, the directory /var/cpanel/open-xchange/subadmin should be empty and when you run /usr/local/cpanel/bin/oxcpanelenable -X CPANELUSERNAME the dump should contain settings for APP_OX_ADMINPW and APP_OX_MAINDOMAIN.
To change back to the other behaviour
Please be aware, that the transferred archives of the cpanel accounts contain the username and password to be used to provision data in Open-Xchange.
Attention, that will delete the Open-Xchange account! To prevent that, go to the WHM Open-Xchange plugin on the source server and disable that specific account before you terminate it. You can also use the oxcpanelenable tool to do that. Now you can safely terminate the cPanel account on the source server.
In order to access the archived email in cPanel if that feature has been turned on, just follow the instructions given in the IMAP access link within the Email Archiving settings of cPanel.
This link will bring you to an overview and a list of IMAP settings.
Now in Open-Xchange setup this account as an external mail account.
This tool will help you maintaining your integration. It can be used to check the integration as well as enable/disable single or all accounts on the cPanel server.
<NAME> := a cpanel user name OR a perl regular expression like '.*'
Note: None of the operations of the tool will actually remove anything on the Open-Xchange server. Where the enable operation creates accounts on Open-Xchange, disable won't remove those! Removing accounts must be done manually on the Open-Xchange server. The tool will also NOT repair incomplete or broken accounts on the Open-Xchange side. It can be used to maintain the LOCAL state of the Open-Xchange<->cPanel connection.