How to Customize Roundcube Webmail
- When you upgrade to cPanel & WHM version 58, you will lose all of your prior Roundcube customizations.
- The instructions in this document only apply to cPanel & WHM versions 11.46 through 56. Customizations that use this method will not function in cPanel & WHM version 58 and later, because these versions ship Roundcube as an RPM. To customize Roundcube for cPanel & WHM version 58 and later, read our How to Build and Install Custom RPMs documentation.
- Customization of Roundcube gives you full control over the end user experience. However, cPanel, Inc. does not support these customizations.
This document explains how to update the Roundcube webmail application, and how you can customize your Roundcube installation.
/usr/local/cpanel/bin/update-roundcube script only retains the last four backups, continuous execution of the
/usr/local/cpanel/bin/update-roundcube script may cause data loss. We strongly recommend that you maintain external backups and avoid continuous backups of non-operational Roundcube installations.
The method that cPanel & WHM uses to update Roundcube affects your customizations. cPanel & WHM uses the following process to update Roundcube:
- The system runs the
/scripts/upcpscript to update cPanel & WHM.
/scripts/upcpscript runs the
/usr/local/cpanel/install/webmailscript executes the
/usr/local/cpanel/bin/update-roundcubescript runs the following command to remove the current Roundcube installation:
rm -rf /usr/local/cpanel/base/3rdparty/roundcube
/usr/local/cpanel/bin/update-roundcubescript extracts the appropriate source tarball to the
During this step, the
/usr/local/cpanel/bin/update-roundcubescript checks for the existence of the
- If that file exists and is executable, the
/usr/local/cpanel/bin/update-roundcubescript executes it and terminates.
- This bypasses cPanel & WHM’s manipulation of the Roundcube configuration files.
- If the file successfully executes, steps 5 through 9 of the installation procedure do not occur.
- If the
/var/cpanel/roundcube/installfile exists but is not executable, the file contents print to
STDOUTand the normal cPanel & WHM configuration of Roundcube continues with the installation procedure.
- If that file exists and is executable, the
/usr/local/cpanel/bin/update-roundcubescript changes the ownership of the Roundcube installation to the
rootuser and the
/usr/local/cpanel/bin/update-roundcubescript checks for the existance of the
/usr/local/cpanel/bin/update-roundcubescript extracts MySQL® configuration values from the system settings.
/usr/local/cpanel/bin/update-roundcubescript backs up Roundcube’s MySQL database to the
currenttimestamprepresents the time at which the script ran.
/var/cpanel/roundcube/directory only retains the four most recent copies of the Roundcube database backup.
/usr/local/cpanel/bin/update-roundcubescript drops the Roundcube database from MySQL.
/usr/local/cpanel/bin/update-roundcubescript updates Roundcube’s configuration files and MySQL files with the server’s settings.
/usr/local/cpanel/bin/update-roundcubescript recreates Roundcube’s database from the MySQL files.
/usr/local/cpanel/bin/update-roundcubescript reloads the previous Roundcube database backup and finishes the update.
Install a customized instance of Roundcube
You may customize Roundcube in a number of ways. For example, you can make simple configuration changes or completely replace the Roundcube tarball.
Where to save a custom Roundcube tarball
During step 2 of the installation procedure, the
/usr/local/cpanel/bin/update-roundcube script checks for custom Roundcube tarballs. If any of these tarball files exist, cPanel & WHM uses them instead of the cPanel-provided tarball.
If the script locates multiple tarballs, it uses them in the following order:
||Use this location for a compressed tarball that you want to apply to a specific Roundcube version.|
||Use this location for an uncompressed tarball that you want to apply to a specific Roundcube version.|
||Use this location for a compressed tarball that you want to apply to Roundcube regardless of version.|
||Use this location for an uncompressed tarball that you want to apply to Roundcube regardless of version.|
For example, cPanel & WHM uses the
/var/cpanel/roundcube/roundcube-0.4-local.tar.gz file if the following statements are true:
/var/cpanel/roundcube/roundcube-0.4-local.tar.gzfile matches the version number that the
- The value that
$RCUBE_VERSIONrepresents in these locations must match the
$RCUBE_VERSIONvariable that the
- For example, if the
$RCUBE_VERSIONparameter is set to the
0.4version in the
/usr/local/cpanel/bin/update-roundcubescript, save your custom tarball as the
- These tarballs must extract to the
Where to store a custom overlay file
The overlay tarball allows you to customize specific aspects of Roundcube. For example, you can use an overlay to change graphics, themes, or plugins. It can also contain one image file.
The overlay does not need to contain a complete Roundcube distribution. It only needs to contain the components that you wish to modify, because cPanel & WHM will overlay it onto the Roundcube installation. The overlay does, however, need to contain a directory structure that matches the structure of the
/usr/local/cpanel/base/3rdparty/roundcube directory and starts with
After you determine which tarball to use for the source install and extract it, the
/usr/local/cpanel/bin/update-roundcube script checks for the directories listed in the table below:
||Use this location for a compressed overlay you want to apply to a specific Roundcube version.|
||Use this location for an uncompressed overlay you want to apply to a specific Roundcube version.|
||Use this location for a compressed overlay you want to apply to Roundcube regardless of version.|
||Use this location for an uncompressed overlay you want to apply to Roundcube regardless of version.|
- If the script locates multiple tarballs, it uses them in this order.
- The value of the
$RCUBE_VERSIONvariable must match the version number that the