How to Customize SquirrelMail


Warnings:
  • This document is only valid for cPanel & WHM version 72 and earlier.
    • We deprecated SquirrelMail and its functionality in cPanel & WHM version 76 and earlier and removed it in cPanel & WHM version 78.
    • For more information about SquirrelMail’s deprecation and removal, read our cPanel Deprecation Plan documentation.
  • Because cPanel, L.L.C. doesn’t develop SquirrelMail, cPanel Technical Support can’t help with customization.

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.

Important:
  • In cPanel & WHM version 56 through 74, we shipped SquirrelMail as an RPM. To customize your SquirrelMail RPM, follow the directions in the How to Build and Install Custom RPMs documentation.
  • Customization of SquirrelMail gives you full control over the end user experience. However, cPanel, L.L.C. does not support these customizations.

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.

Important:

Before you run the configuration test for SquirrelMail from a remote server, you must add the following line to the /usr/local/cpanel/base/3rdparty/squirrelmail/config/config_local.php file:

    $allow_remote_configtest = true;