Open-Xchange cPanel Installation: Difference between revisions

From Open-Xchange
 
(107 intermediate revisions by 6 users not shown)
Line 1: Line 1:
= Install Open-Xchange on WHM/cPanel =
= Install Open-Xchange on WHM/cPanel =


'''BETA'''
== Requirements ==
 
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 [https://documentation.cpanel.net/display/ALD/cPanel%2520&%2520WHM%2520Long-Term%2520Support#cPanel&WHMLong-TermSupport-ScheduleforLong-TermSupportReleasesofcPanel&WHM 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
 
UPDATES=manual
 
in <tt>/etc/cpupdate.conf</tt>
 
== Changelog ==
 
=== 1.1.3-rev2 ===
 
* Support for cPanel 11.44 and 11.46 ('''Note:''' support for 11.46 no longer available in the meantime)
* Bugfixes
** Bugfix #34582 - park/unpark domain does not work
** Bugfix #34271 - special characters in passwords break cpanel to open-xchange webmail autologin
** Bugfix #29361 - path to ModuleAccessDefinitions.properties wrong in ox configuration
** Bugfix #30546 - Errors do net get handled when performing cPanel tasks
 
=== 1.1.2-rev1 ===
 
* Improved cPanel account transfer
** ability to change where to store integration metadata like oxpassword (file/cpuser)
* Display the context id of main domain in WHM plugin when "Addon domain creates a new context" has been set to “Yes”
* Bugfixes
** Bugfix #30546 - Errors do net get handled when performing cPanel tasks
** Bugfix #29868 - [L3] cPanel account transfer does not alter imapserver/smtp server when transferred account did already exist in Open-Xchange
** Bugfix #29932 - Transfer accounts: OX Enabled status not set when transferring from non-ox cpanel
** Bugfix #29933 - Transfer accounts: Addon domains not created
 
=== 1.1.1-rev2 ===
 
* Support for cPanel version 11.40
* Fixed UI/CSS  of WHM plugin
* Introduced separate setting for the “autologin” URL
* Improved oxcpanelenable commandline tool
* Initial support for transferring cPanel accounts between servers
* Several Bugfixes
** Bugfix #29773 - Unable to login as webmail user after changing cPanel account name
** Bugfix #29764 - [L3] Wrong 'Default Infostore quota (0=unlimited)'  documentation in cpanel module
** Bugfix #29707 - renaming domain and account in one step fails
** Bugfix #29708 - renaming domain drops all addon domains
** Bugfix #29712 - addon domain handling broken in multiple whm/one open-xchange mode
** Bugfix #29530 - Unable to "terminate" account; do not try to delete an account that isn't there...
 
=== 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 ==
== Mode of operation ==


It is recommended to run Open-Xchange on one or more separate machines. See the "''Hosting Edition deployment tutorials''" at [[Main_Page_HESE#quickinstall]].
It is recommended to run Open-Xchange on one or more separate machines. See the "''Hosting Edition deployment tutorials''" at  
 
* [[Main_Page_HESE#quickinstall|Open-Xchange Server 6]]
* [[AppSuite:Main_Page_AppSuite#quickinstall|OX App Suite]]
 
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.
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.


Line 12: Line 75:
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.
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.
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 ==
== Known issues ==


* users with the same email localpart from different domains in a single cpanel account and a single context do not work because user names as well as display names must be unique
{{CPanelKnownIssues}}
* cpanel account names cannot be renamed when using the ox integration
 
* error handling needs to be improved.
==Release Notes==
* addon domain handling needs to be improved
 
* unable to indicate errors in open-xchange account creation when adding users in WHM/cPanel because the WHM/cPanel hooks have no possibility to transport any error to the ui.
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 installation guides listed in [[Open-Xchange_cPanel_Installation#Mode_of_operation|here]] to install Open-Xchange and either just install the packages
 
'''On OX6''':
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''':


== Debugging ==
* 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>


* run the command
'''Important:'''
$ 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''' create a context, just follow the installation guide up to the database registration
* Add the following argument to initconfigdb (only for OX App Suite version 7.10.1 and before): <tt>--addon-sql "reseller.sql autocid.sql"</tt>


== Install and prepare Open-Xchange ==
== Preparation ==


* Follow one of the [http://oxpedia.org/index.php?title=Main_Page_HESE Open-Xchange installation guides] to install Open-Xchange '''with 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-plugin-reseller-soap</tt> from the repository http://software.open-xchange.com/OX6/OXtender-unstable/cPanel/ (see below)
** add the following argument to initconfigdb: <tt>--addon-sql "reseller.sql autocid.sql"</tt>
** instead of <tt>open-xchange-authentication-database</tt>, install the package <tt>open-xchange-authentication-imap</tt>
** do '''NOT''' create a context, just follow the installation guide up to the database registration
* run the command
* run the command
  $ /opt/open-xchange/sbin/initrestrictions -A oxadminmaster -P secret
  $ /opt/open-xchange/sbin/initrestrictions -A oxadminmaster -P secret
once you've finished the open-xchange installation
once you've finished the open-xchange installation
* 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 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.
* edit file <tt>/opt/open-xchange/etc/groupware/imapauth.properties</tt> and set
* 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
  USE_MULTIPLE=true
* edit file <tt>/opt/open-xchange/etc/groupware/settings/open-xchange-gui-wizard-plugin.properties</tt> and set
* edit file <tt>/opt/open-xchange/etc/mail.properties</tt> and set
ui/wizard/firstrunmode=true
* edit file <tt>/opt/open-xchange/etc/groupware/mail.properties</tt> and set
  com.openexchange.mail.adminMailLoginEnabled=true
  com.openexchange.mail.adminMailLoginEnabled=true
* edit file <tt>/opt/open-xchange/etc/groupware/sessiond.properties</tt> and set
* edit file <tt>/opt/open-xchange/etc/sessiond.properties</tt> and set
  com.openexchange.sessiond.autologin=true
  com.openexchange.sessiond.autologin=true
* edit file <tt>/opt/open-xchange/etc/admindaemon/User.properties</tt> and set
* edit file <tt>/opt/open-xchange/etc/AdminUser.properties</tt> and set
  PRIMARY_MAIL_UNCHANGEABLE=false
  PRIMARY_MAIL_UNCHANGEABLE=false
USERNAME_CHANGEABLE=true
* allow access from the cPanel server, edit <tt>/etc/httpd/conf.d/proxy_ajp.conf</tt> or <tt>/etc/httpd/conf.d/proxy_http.conf</tt>


{{InstallPlugin|reponame=oxcpintegration|pluginname=open-xchange-admin-plugin-reseller-soap|sopath=OXtender-unstable/cPanel|reponame=cpanelbeta}}
<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>


== Install and prepare WHM/cPanel on CentOS5 ==
'''Important: It is required to NOT set MASTER_AUTHENTICATION_DISABLED=true or CONTEXT_AUTHENTICATION_DISABLED=true in <tt>/opt/open-xchange/etc/AdminDaemon.properties</tt>'''


'''Note: Choose either CentOS5 or RHEL5. Nothing else is supported to integrate Open-Xchange with cPanel.'''
== 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
* Follow the installation guide http://docs.cpanel.net/twiki/bin/view/AllDocumentation/InstallationGuide/Quick-StartInstallationGuide
* run <tt>/scripts/upcp</tt>
* run <tt>/scripts/upcp</tt>
* run <tt>/scripts/perlinstaller SOAP::Lite</tt>
* run <tt>/scripts/perlinstaller SOAP::Lite</tt> (not needed with cPanel 11.44 or newer)
'''NOTE: This can take very long and it might look like it is hanging at'''
'''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
  We are about to install SOAP::Lite and for your convenience will provide
Line 76: Line 161:


Just be patient and wait for it to finish.
Just be patient and wait for it to finish.
* add the repository http://software.open-xchange.com/OX6/OXtender-unstable/cPanel/RHEL5 to your yum configuration
 
* 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=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
 
=== yum repo config on x86_64 ===
 
  $ vi /etc/yum.repos.d/oxintegration.repo
  $ vi /etc/yum.repos.d/oxintegration.repo
  [oxcpintegration]
  [oxcpintegration]
  name=Open-Xchange cPanel
  name=Open-Xchange cPanel
  baseurl=http://LDBACCOUNT:LDBPASSWORD@software.open-xchange.com/OX6/OXtender-unstable/cPanel/RHEL5
  baseurl=https://LDBACCOUNT:LDBPASSWORD@software.open-xchange.com/components/cPanel/stable/RHEL6
  gpgkey=http://software.open-xchange.com/oxbuildkey.pub
  gpgkey=http://software.open-xchange.com/oxbuildkey.pub
  enabled=1
  enabled=1
  gpgcheck=1
  gpgcheck=1
  metadata_expire=0m
  metadata_expire=0m
#IMPORTANT!!!!!
exclude=*.i386


* install the package <tt>open-xchange-cpanel</tt>
* install the package <tt>open-xchange-cpanel</tt>
Line 101: Line 212:
  $ /usr/local/cpanel/bin/oxcpanelenable -h
  $ /usr/local/cpanel/bin/oxcpanelenable -h
for more information.
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 ==
* 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.
* The name of each context admin account is the same as the corresponding cpanel account name.
* and the password of the admin can be found in <tt>/var/cpanel/open-xchange/subadmin/<CPACCOUNT>/.oxadminpw</tt>
== Troubleshooting ==
Creation of Accounts in Open-Xchange does not work?
Please check the following:
=== Check connection between Open-Xchange and cPanel (connector) ===
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'''
=== Check whether cPanel Hooks are available ===
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
must output
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
=== Context listing in WHM does not work or Mailaccounts in cPanel are not listed in Open-Xchange ===
Check for [[Open-Xchange_cPanel_Installation#Known_issues|known issues]], e.g. you might been hit by a bug in SOAP::Lite.
= 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|800px]]
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|800px]]
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.
= "Copy an Account From Another Server" support =
[[File:Copy accounts.png|800px]]
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.
== Concepts ==
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 <tt>/var/cpanel/open-xchange/subadmin/<CPANELACCOUNT></tt>
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
PASSWORD_STORE=cpuser
to <tt>/var/cpanel/open-xchange/ox.conf</tt>
'''Note:'''
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 <tt>/usr/local/cpanel/bin/oxcpanelenable</tt>
must be used.
== Example ==
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
# add <tt>PASSWORD_STORE=cpuser</tt> to <tt>/var/cpanel/open-xchange/ox.conf</tt>
# run the command <tt>/usr/local/cpanel/bin/oxcpanelenable -m dir2cpuser</tt>
After you've done that, the directory <tt>/var/cpanel/open-xchange/subadmin</tt> should be empty and
when you run <tt>/usr/local/cpanel/bin/oxcpanelenable -X CPANELUSERNAME</tt> the dump should contain
settings for <tt>APP_OX_ADMINPW</tt> and <tt>APP_OX_MAINDOMAIN</tt>.
To change back to the other behaviour
# remove <tt>PASSWORD_STORE=cpuser</tt> from <tt>/var/cpanel/open-xchange/ox.conf</tt>
# run the command <tt>/usr/local/cpanel/bin/oxcpanelenable -m cpuser2dir</tt>
== Security ==
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.
== Pitfalls ==
=== Delete account on source server when both connect to the same Open-Xchange server ===
'''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 [[Open-Xchange_cPanel_Installation#The_tool_.2Fusr.2Flocal.2Fcpanel.2Fbin.2Foxcpanelenable|oxcpanelenable tool]] to do that.
Now you can safely terminate the cPanel account on the source server.
= How to access the mail archive from within Open-Xchange webmail =
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.
[[File:CPanel_IMAP_Access_instruction_Link.png|800px]]
This link will bring you to an overview and a list of IMAP settings.
[[File:CPanel_IMAP_Access_Instructions.png|800px]]
Now in Open-Xchange setup this account as an external mail account.
= The tool <tt>/usr/local/cpanel/bin/oxcpanelenable</tt> =
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.
== Function overview ==
<tt>&lt;NAME&gt;</tt> := a cpanel user name OR a perl regular expression like '.*'
;/usr/local/cpanel/bin/oxcpanelenable --list|-l: Lists all cPanel accounts including webmail accounts and the status on whether they are enabled or not.
;/usr/local/cpanel/bin/oxcpanelenable --enableall|-e [-f]: Enable all cPanel accounts which means that an Open-Xchange account will be created for each local cPanel account. Use '''-f''' (force) to set enabled status even when the operation fails.
;/usr/local/cpanel/bin/oxcpanelenable --enable|-E <NAME> [-f]: Enable a single account matching the <NAME> pattern. Use '''-f''' (force) to set enabled status even when the operation fails.
;/usr/local/cpanel/bin/oxcpanelenable --disable|-d <NAME>: Disable a single account or all accounts matching the <NAME> pattern.
;/usr/local/cpanel/bin/oxcpanelenable --dumpuser|-X <NAME>: Dump the cPanel internals of a single account or all accounts matching the <NAME> pattern.
;/usr/local/cpanel/bin/oxcpanelenable --checkox|-c: Check the interconnection between Open-Xchange and cPanel
;/usr/local/cpanel/bin/oxcpanelenable ---migmeta|-m [cpuser2dir|dir2cpuser]: Migrate integration metadata between local files and cpuser store
'''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.

Latest revision as of 12:58, 15 January 2019

Install Open-Xchange on WHM/cPanel

Requirements

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

UPDATES=manual

in /etc/cpupdate.conf

Changelog

1.1.3-rev2

  • Support for cPanel 11.44 and 11.46 (Note: support for 11.46 no longer available in the meantime)
  • Bugfixes
    • Bugfix #34582 - park/unpark domain does not work
    • Bugfix #34271 - special characters in passwords break cpanel to open-xchange webmail autologin
    • Bugfix #29361 - path to ModuleAccessDefinitions.properties wrong in ox configuration
    • Bugfix #30546 - Errors do net get handled when performing cPanel tasks

1.1.2-rev1

  • Improved cPanel account transfer
    • ability to change where to store integration metadata like oxpassword (file/cpuser)
  • Display the context id of main domain in WHM plugin when "Addon domain creates a new context" has been set to “Yes”
  • Bugfixes
    • Bugfix #30546 - Errors do net get handled when performing cPanel tasks
    • Bugfix #29868 - [L3] cPanel account transfer does not alter imapserver/smtp server when transferred account did already exist in Open-Xchange
    • Bugfix #29932 - Transfer accounts: OX Enabled status not set when transferring from non-ox cpanel
    • Bugfix #29933 - Transfer accounts: Addon domains not created

1.1.1-rev2

  • Support for cPanel version 11.40
  • Fixed UI/CSS of WHM plugin
  • Introduced separate setting for the “autologin” URL
  • Improved oxcpanelenable commandline tool
  • Initial support for transferring cPanel accounts between servers
  • Several Bugfixes
    • Bugfix #29773 - Unable to login as webmail user after changing cPanel account name
    • Bugfix #29764 - [L3] Wrong 'Default Infostore quota (0=unlimited)' documentation in cpanel module
    • Bugfix #29707 - renaming domain and account in one step fails
    • Bugfix #29708 - renaming domain drops all addon domains
    • Bugfix #29712 - addon domain handling broken in multiple whm/one open-xchange mode
    • Bugfix #29530 - Unable to "terminate" account; do not try to delete an account that isn't there...

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

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.

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, please contact Open-Xchange

Known issues

  • open-xchange icon not shown in cpanel in version 11.46.3
  • new paper_lantern theme not supported
  • Users with the same email localpart from different domains in a single cPanel account and a single context do not work because user names as well as display names must be unique
  • cPanel account names cannot be renamed when using the ox integration
  • Accessing the mail archiving does not automatically work in Open-Xchange webmail
  • park/unpark domain does not work

Release Notes

To download the Release Notes, follow this: Download

Install and prepare Open-Xchange

Follow one of the installation guides listed in here to install Open-Xchange and either just install the packages

On OX6:

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:

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

Important:

  • Do NOT create a context, just follow the installation guide up to the database registration
  • Add the following argument to initconfigdb (only for OX App Suite version 7.10.1 and before): --addon-sql "reseller.sql autocid.sql"

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 open-xchange-gui-wizard-plugin open-xchange-gui-wizard-plugin-gui. The wizard must be used to enforce the user to provide a real valid displayname.
  • On OX6 edit file /opt/open-xchange/etc/settings/open-xchange-gui-wizard-plugin.properties and set
ui/wizard/firstrunmode=true
  • edit file /opt/open-xchange/etc/imapauth.properties and set
USE_MULTIPLE=true
  • edit file /opt/open-xchange/etc/mail.properties and set
com.openexchange.mail.adminMailLoginEnabled=true
  • edit file /opt/open-xchange/etc/sessiond.properties and set
com.openexchange.sessiond.autologin=true
  • edit file /opt/open-xchange/etc/AdminUser.properties and set
PRIMARY_MAIL_UNCHANGEABLE=false
USERNAME_CHANGEABLE=true
  • allow access from the cPanel server, edit /etc/httpd/conf.d/proxy_ajp.conf or /etc/httpd/conf.d/proxy_http.conf
<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

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

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

yum repo config on x86_64

$ 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


  • install the package open-xchange-cpanel
$ 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

  • All errors happening during cPanel account creation and mail account creation are logged into the files /usr/local/cpanel/logs/open-xchange_log and /usr/local/cpanel/logs/error_log. If something does not work, check these logs first!
  • /usr/local/cpanel/bin/oxcpanelinstall 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 /opt/open-xchange/etc/AdminDaemon.properties because this will mess up authentication using the Connector for cPanel, see Reseller_Bundle#Setup_and_Configuration for more information.
  • The name of each context admin account is the same as the corresponding cpanel account name.
  • and the password of the admin can be found in /var/cpanel/open-xchange/subadmin/<CPACCOUNT>/.oxadminpw

Troubleshooting

Creation of Accounts in Open-Xchange does not work? Please check the following:

Check connection between Open-Xchange and cPanel (connector)

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

Check whether cPanel Hooks are available

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

must output

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

Context listing in WHM does not work or Mailaccounts in cPanel are not listed in Open-Xchange

Check for known issues, e.g. you might been hit by a bug in SOAP::Lite.

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.

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.

Whm-ox-enable.png

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

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 /usr/local/cpanel/logs/open-xchange_log and /usr/local/cpanel/logs/error_log.

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

"Copy an Account From Another Server" support

Copy accounts.png

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.

Concepts

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

PASSWORD_STORE=cpuser

to /var/cpanel/open-xchange/ox.conf

Note:

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.

Example

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

  1. add PASSWORD_STORE=cpuser to /var/cpanel/open-xchange/ox.conf
  2. run the command /usr/local/cpanel/bin/oxcpanelenable -m dir2cpuser

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

  1. remove PASSWORD_STORE=cpuser from /var/cpanel/open-xchange/ox.conf
  2. run the command /usr/local/cpanel/bin/oxcpanelenable -m cpuser2dir

Security

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.

Pitfalls

Delete account on source server when both connect to the same Open-Xchange server

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.

How to access the mail archive from within Open-Xchange webmail

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.

CPanel IMAP Access instruction Link.png

This link will bring you to an overview and a list of IMAP settings.

CPanel IMAP Access Instructions.png

Now in Open-Xchange setup this account as an external mail account.

The tool /usr/local/cpanel/bin/oxcpanelenable

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.

Function overview

<NAME> := a cpanel user name OR a perl regular expression like '.*'

/usr/local/cpanel/bin/oxcpanelenable --list|-l
Lists all cPanel accounts including webmail accounts and the status on whether they are enabled or not.
/usr/local/cpanel/bin/oxcpanelenable --enableall|-e [-f]
Enable all cPanel accounts which means that an Open-Xchange account will be created for each local cPanel account. Use -f (force) to set enabled status even when the operation fails.
/usr/local/cpanel/bin/oxcpanelenable --enable|-E <NAME> [-f]
Enable a single account matching the <NAME> pattern. Use -f (force) to set enabled status even when the operation fails.
/usr/local/cpanel/bin/oxcpanelenable --disable|-d <NAME>
Disable a single account or all accounts matching the <NAME> pattern.
/usr/local/cpanel/bin/oxcpanelenable --dumpuser|-X <NAME>
Dump the cPanel internals of a single account or all accounts matching the <NAME> pattern.
/usr/local/cpanel/bin/oxcpanelenable --checkox|-c
Check the interconnection between Open-Xchange and cPanel
/usr/local/cpanel/bin/oxcpanelenable ---migmeta|-m [cpuser2dir|dir2cpuser]
Migrate integration metadata between local files and cpuser store

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.