Customizing SquirrelMail

This document explains how cPanel updates SquirrelMail, and how you can customize your SquirrelMail installation.

Important: These methods for customizing SquirrelMail 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 SquirrelMail installation, it is useful to understand how cPanel updates SquirrelMail.

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

The update-squirrelmail script then does the following:

1. Removes the existing SquirrelMail installation (via the command rm -rf /usr/local/cpanel/base/3rdparty/squirrelmail).
2. Using the version specified in update-squirrelmail, extracts the appropriate SquirrelMail source tarball to /usr/local/cpanel/base/3rdparty.
3. Changes ownership of the SquirrelMail installation to the user root and the group wheel.
4. Changes the SquirrelMail data directory's permissions to 755.
5. Extracts configuration values for maildir and mbox from the system settings.
6. Copies the appropriate IMAP configuration into place.

Installing a Customized Instance of SquirrelMail

There are several ways to customize the SquirrelMail installation. Options range from making simple configuration changes to completely replacing the cPanel-supplied SquirrelMail tarball.

For instructions on customizing SquirrelMail, see the SquirrelMail documentation.

Where to place a custom SquirrelMail tarball

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

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

If any of those tarballs exist, they are used in lieu 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/squirrelmail/squirrelmail-local.tar and /var/cpanel/squirrelmail/squirrelmail-1.49a-local.tar.gz exist, the latter will be used, assuming its version number is specified in the update-squirrelmail script.
• The value represented by $sqversion must match the sqversion variable defined in update-squirrelmail. Thus, in update-squirrelmail, if sqversion='1.49a', the custom tarball should be named squirrelmail-1.49a-local.tar.gz.
• As with the tarball supplied by cPanel, these tarballs must extract to a directory named squirrelmail, all lowercase and without a version number.
  • The end result is the directory /usr/local/cpanel/base/3rdparty/squirrelmail

Where to place a custom overlay file

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

The overlay need not contain a complete SquirrelMail distribution. It only needs to contain the components to be modified, since it will be "overlaid" onto the SquirrelMail installation. The overlay can contain 1 image file, for example.

It does, however, need to contain a directory structure that mimics /usr/local/cpanel/base/3rdparty/squirrelmail — but starts with squirrelmail.

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

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

As with the custom SquirrelMail tarballs above,

• If the script locates multiple tarballs, it will use the one furthest down the list.
• The value of $sqversion must match the version number specified in the update-squirrelmail script.

Preventing cPanel from modifying the SquirrelMail configuration files

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

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