Customizing Roundcube Webmail

This document explains how cPanel updates the Roundcube webmail application, and how you can customize your Roundcube installation.

Important: These methods for customizing Roundcube allow you full control over the end user experience. However, such customizations fall outside the range of support cPanel offers.

General Installation Procedure

Before you customize your Roundcube installation, it is useful to understand how cPanel updates Roundcube.

When the cPanel update script (/scripts/upcp) runs, it executes the webmail script found at /usr/local/cpanel/install/webmail. This, in turn, executes /usr/local/cpanel/bin/update-roundcube.

The update-roundcube script then does the following:

1. Removes the existing Roundcube installation (via the command rm -rf /usr/local/cpanel/base/3rdparty/roundcube).
2. Extracts the appropriate Roundcube source tarball to /usr/local/cpanel/base/3rdparty using the version specified in update-roundcube.
3. Changes the ownership of the Roundcube installation to the root user and the wheel group.
4. Extracts configuration values for Maildir, mbox, and MySQL from the system settings.
5. Backs up the MySQL Roundcube database to /var/cpanel/roundcube/roundcube.backup.sql.«current timestamp».
   • Please note that only 4 copies of the Roundcube database backup are retained in /var/cpanel/roundcube.
6. Drops the Roundcube database from MySQL.
7. Updates the Roundcube configuration files and Roundcube database SQL files with the server's settings.
8. Recreates the Roundcube database from the provided SQL files.
9. Reloads the previous Roundcube database backup, finishing the Roundcube update.

Installing a Customized Instance of Roundcube

You may customize Roundcube in a number of ways. You may make simple configuration changes or completely replace the Roundcube tarball.

For instructions on customizing Roundcube, see the Roundcube wiki.

Where to place a custom Roundcube tarball

During step 2 of the General Installation Procedure above, the update-roundcube script checks for custom Roundcube tarballs in the following locations:

• /var/cpanel/roundcube/roundcube-local.tar — Use this location for an uncompressed tarball you want to apply to Roundcube regardless of version.
• /var/cpanel/roundcube/roundcube-local.tar.gz — Use this location for a compressed tarball you want to apply to Roundcube regardless of version.
• /var/cpanel/roundcube/roundcube-$RCUBE_VERSION-local.tar — Use this location for an uncompressed tarball you want to apply to a specific Roundcube version.
• /var/cpanel/roundcube/roundcube-$RCUBE_VERSION-local.tar.gz — Use this location for a compressed tarball you want to apply to a specific Roundcube version.

If any of the tarballs listed above exist, they are used instead of the tarball supplied by cPanel.

• If the script locates multiple tarballs, it will use the one furthest down the list above.
  • For example, if both /var/cpanel/roundcube/roundcube-local.tar and /var/cpanel/roundcube/roundcube-0.4-local.tar.gz exist, the latter will be used, assuming its version number is specified in the update-roundcube script.
• The value represented by $RCUBE_VERSION must match the $RCUBE_VERSION variable defined in update-roundcube. Thus, in update-roundcube, if $RCUBE_VERSION='0.4', the custom tarball should be named roundcube-0.4-local.tar.gz.
• As with the tarball supplied by cPanel, these tarballs must extract to a directory named roundcube, all lowercase and without a version number.
  • The end result is the directory /usr/local/cpanel/base/3rdparty/roundcube

Where to place a custom overlay file

The overlay tarball provides a simple way of customizing specific aspects of Roundcube. For example, you can use an overlay to change graphics, themes, modules, plugins and the like.

The overlay file does not need to contain a complete Roundcube distribution. It only needs to contain the components you wish to modify. This is because the file will be "overlaid" on top of the Roundcube installation. For example, the overlay can contain 1 image file.

The overlay file needs to contain a directory structure that mimics /usr/local/cpanel/base/3rdparty/roundcube — but starts in the roundcube directory.

After determining which tarball to use for the source install, and extracting it, the update-roundcube script checks for the following:

• /var/cpanel/roundcube/overlay.tar — Use this location for an uncompressed overlay you want to apply to Roundcube regardless of version.
• /var/cpanel/roundcube/overlay.tar.gz — Use this location for a compressed overlay you want to apply to Roundcube regardless of version.
• /var/cpanel/roundcube/overlay.$RCUBE_VERSION.tar — Use this location for an uncompressed overlay you want to apply to a specific Roundcube version.
• /var/cpanel/roundcube/overlay.$RCUBE_VERSION.tar.gz — Use this location for a compressed overlay you want to apply to a specific Roundcube version.

If any of the tarballs listed above exist, they are used instead of the tarball supplied by cPanel.

• If the script locates multiple tarballs, it will use the one furthest down the list above.
  • For example, if both /var/cpanel/roundcube/overlay.tar and /var/cpanel/roundcube/overlay.0.4.tar.gz exist, the latter will be used, assuming its version number is specified in the update-roundcube script.
• The value represented by $RCUBE_VERSION must match the $RCUBE_VERSION variable defined in update-roundcube. Thus, in update-roundcube, if $RCUBE_VERSION='0.4', the custom tarball should be named overlay.0.4.tar.gz.
• As with the tarball supplied by cPanel, these tarballs must extract to a directory named roundcube, all lowercase and without a version number.
  • The end result is the directory /usr/local/cpanel/base/3rdparty/roundcube

Preventing cPanel from modifying the Roundcube configuration files

Immediately after step 3 in the General Installation Procedure above, and before step 4, update-roundcube checks for the existence of /var/cpanel/roundcube/install.

• If that file exists and is executable, the update-roundcube script will execute it and terminate, thus bypassing cPanel's manipulation of the Roundcube configuration files.
  • In this case, steps 4 – 9 of the General Installation Procedure do not occur.
• If /var/cpanel/roundcube/install exists but is not executable, the file contents will be printed to STDOUT and the normal cPanel configuration of Roundcube will continue with the remaining steps detailed in the General Installation Procedure.

Warning: Because the SQL data backup performed by update-roundcube only retains the last 4 backups, continuous execution of update-roundcube may cause you to lose your data. We strongly recommend that you maintain external backups and avoid continuous backups of non-operational Roundcube installation.