How to Customize SquirrelMail

Overview

This document explains how cPanel & WHM versions 11.44 and earlier update the SquirrelMail webmail application, and how you can customize your SquirrelMail installation.

General installation procedure

Before you customize your SquirrelMail installation, it is useful to understand how cPanel & WHM updates SquirrelMail.

1. The /scripts/upcp script runs to update cPanel & WHM.
2. It also executes the /usr/local/cpanel/install/webmail script.
3. The /usr/local/cpanel/install/webmail script then executes the /usr/local/cpanel/bin/update-squirrelmail script.

The /usr/local/cpanel/bin/update-squirrelmail script performs the following actions:

1. It uses the following command to remove the current SquirrelMail installation:

   rm -rf /usr/local/cpanel/base/3rdparty/squirrelmail

2. It extracts the appropriate SquirrelMail source tarball to the /usr/local/cpanel/base/3rdparty/ directory.

   Note:

   For more information, read the Where to place a custom SquirrelMail tarball section below.

3. It changes the ownership of the SquirrelMail installation to the root user and the wheel group.

4. It changes the SquirrelMail data directory’s permissions to 755.

5. It checks for the existence of the /var/cpanel/squirrelmail/install file.

   Note:

   For more information, read the Prevent changes to the SquirrelMail configuration files section below.

6. It extracts IMAP configuration values and copies them into place.

Prevent changes to the SquirrelMail configuration files

During Step 5 of the installation procedure, the /usr/local/cpanel/bin/update-squirrelmail script checks for the existence of the /var/cpanel/squirrelmail/install file.

• If that file exists and is executable, the /usr/local/cpanel/bin/update-squirrelmail script executes it and terminates.

  Notes:

  • This bypasses cPanel & WHM’s manipulation of the SquirrelMail configuration files.
  • Step 6 of the installation procedure does not occur.
    

• If the /var/cpanel/squirrelmail/install file exists but is not executable, the file contents print to STDOUT and the normal cPanel & WHM configuration of SquirrelMail continues for the remaining steps.

Install a customized instance of SquirrelMail

There are several ways to customize the SquirrelMail installation. For instructions on how to create a custom SquirrelMail tarball, read the SquirrelMail documentation.

Where to place a custom SquirrelMail tarball

For more information about how to place a custom SquirrelMail tarball, read the following non-sequential steps:

• When the /usr/local/cpanel/bin/update-squirrelmail script runs, it checks for custom SquirrelMail tarballs. The following list lists the locations it checks:

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

    If any of those tarballs exist, the /usr/local/cpanel/bin/update-squirrelmail script uses that tarball instead of the cPanel-supplied tarball. cPanel & WHM uses the locations in the above list in the listed order.
    For example, if the following statements are true, cPanel & WHM uses the /var/cpanel/squirrelmail/squirrelmail-1.49a-local.tar.gz file:
    * Both the /var/cpanel/squirrelmail/squirrelmail-local.tar and /var/cpanel/squirrelmail/squirrelmail-1.49a-local.tar.gz files exist.
    * The /var/cpanel/squirrelmail/squirrelmail-1.49a-local.tar.gz file’s version number is specified in the /usr/local/cpanel/bin/update-squirrelmail script.

• The value that $sqversion represents in these locations must match the sqversion variable that the /usr/local/cpanel/bin/update-squirrelmail script defines. For example, if the sqversion parameter is set to the 1.49a version in the /usr/local/cpanel/bin/update-squirrelmail script, save your custom tarball as the squirrelmail-1.49a-local.tar.gz file.

  Important:

  These tarballs must extract to the /usr/local/cpanel/base/3rdparty/squirrelmail/ directory.

Where to place a custom overlay file

For more information about how to place a custom overlay file, read the following non-sequential steps:

• The overlay tarball allows you to customize specific aspects of SquirrelMail.

  Note:

  For example, you can use an overlay to change graphics, themes, or plugins.

• The overlay does not need to contain a complete SquirrelMail distribution. It only needs to contain the components that you wish to modify, because cPanel & WHM overlays it onto the SquirrelMail installation.

  Note:

  For example, it can contain one image file. However, it must contain a directory structure that mimics the structure of the /usr/local/cpanel/base/3rdparty/squirrelmail directory, that that starts with squirrelmail.

• Once you determine which tarball to use for the source install and extract it, the /usr/local/cpanel/bin/update-squirrelmail script checks for the following files:

  • /var/cpanel/squirrelmail/overlay.$sqversion.tar.gz — Use this location for a compressed overlay you want to apply to a specific SquirrelMail 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.tar.gz — Use this location for a compressed overlay you want to apply to SquirrelMail regardless of version.
  • /var/cpanel/squirrelmail/overlay.tar — Use this location for an uncompressed overlay you want to apply to SquirrelMail regardless of version.
    Note:

    As with the custom SquirrelMail tarballs above, the following statements are true:
    * If the script locates multiple tarballs, it will use them in the order that is listed above.
    * The value of the $sqversion variable must match the version number that the /usr/local/cpanel/bin/update-squirrelmail script specifies.

Install SquirrelMail plugins

To enable a SquirrelMail plugin, perform the following steps:

1. Run the /usr/local/cpanel/base/3rdparty/squirrelmail/config/conf.pl command to open the SquirrelMail Configuration menu.

2. Enter the number of the Plugins option. The code block below lists the available SquirrelMail plugins that appear:

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

   Plugins Installed Plugins 1. Login Authentication (login_auth) 3.0 Available Plugins: 2. administrator 3. Bug Report (bug_report) CORE 4. calendar 5. change_password 0.2 6. Demo (demo) CORE 7. filters 8. fortune 9. info 10. listcommands 11. mail_fetch 12. message_details 13. New Mail (newmail) CORE 14. Preview Pane (preview_pane) 2.0 15. sent_subfolders 16. spamcop 17. squirrelspell 0.5 18. Test (test) CORE 19. translate

3. Enter the number of the plugin that you wish to install.

4. Save your changes and exit the SquirrelMail Configuration menu.

To test your new SquirrelMail configuration, navigate to example.com/sessionid/3rdparty/SquirrelMail/src/configtest.php, where example.com represents your domain name, and sessionid represents your current security token.

    $allow_remote_configtest = true;