Page tree
Skip to end of metadata
Go to start of metadata

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:

  • As of cPanel & WHM version 56, SquirrelMail ships 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 Inc. 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:

    $body

  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:

    $body

  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 table lists the locations it checks:

    DirectoryDescription
    /var/cpanel/squirrelmail/squirrelmail-$sqversion-local.tar.gzUse this location for a compressed tarball that you want to apply to a specific SquirrelMail version.
    /var/cpanel/squirrelmail/squirrelmail-$sqversion-local.tarUse this location for an uncompressed tarball that you want to apply to a specific SquirrelMail version.
    /var/cpanel/squirrelmail/squirrelmail-local.tar.gzUse this location for a compressed tarball that you want to apply to SquirrelMail regardless of version.
    /var/cpanel/squirrelmail/squirrelmail-local.tarUse 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:

    $body

  • 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:

    $body

  • 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:

    DirectoryDescription
    /var/cpanel/squirrelmail/overlay.$sqversion.tar.gzUse this location for a compressed overlay you want to apply to a specific SquirrelMail version.
    /var/cpanel/squirrelmail/overlay.$sqversion.tarUse this location for an uncompressed overlay you want to apply to a specific SquirrelMail version.
    /var/cpanel/squirrelmail/overlay.tar.gzUse this location for a compressed overlay you want to apply to SquirrelMail regardless of version.
    /var/cpanel/squirrelmail/overlay.tarUse this location for an uncompressed overlay you want to apply to SquirrelMail regardless of version.

    Note:

    $body

Install SquirrellMail 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:

    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;

 

Additional documentation