How to Customize SquirrelMail
Last modified: April 3, 2020
- This document is only valid for cPanel & WHM version 72 and earlier.
- Because cPanel, L.L.C. doesn’t develop SquirrelMail, cPanel Technical Support can’t help with customization.
This document explains how cPanel & WHM versions 11.44 and earlier update the SquirrelMail webmail application, and how you can customize your SquirrelMail installation.
- 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.
/scripts/upcpscript runs to update cPanel & WHM.
- It also executes the
/usr/local/cpanel/install/webmailscript then executes the
/usr/local/cpanel/bin/update-squirrelmail script performs the following actions:
It uses the following command to remove the current SquirrelMail installation:
rm -rf /usr/local/cpanel/base/3rdparty/squirrelmail
It extracts the appropriate SquirrelMail source tarball to the
For more information, read the Where to place a custom SquirrelMail tarball section below.
It changes the ownership of the SquirrelMail installation to the
rootuser and the
It changes the SquirrelMail data directory’s permissions to
It checks for the existence of the
For more information, read the Prevent changes to the SquirrelMail configuration files section below.
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
If that file exists and is executable, the
/usr/local/cpanel/bin/update-squirrelmailscript 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.
/var/cpanel/squirrelmail/installfile exists but is not executable, the file contents print to
STDOUTand 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:
/usr/local/cpanel/bin/update-squirrelmailscript 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-squirrelmailscript 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.gzfile: * Both the
/var/cpanel/squirrelmail/squirrelmail-1.49a-local.tar.gzfiles exist. * The
/var/cpanel/squirrelmail/squirrelmail-1.49a-local.tar.gzfile’s version number is specified in the
The value that
$sqversionrepresents in these locations must match the
sqversionvariable that the
/usr/local/cpanel/bin/update-squirrelmailscript defines. For example, if the
sqversionparameter is set to the
1.49aversion in the
/usr/local/cpanel/bin/update-squirrelmailscript, save your custom tarball as the
These tarballs must extract to the
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/squirrelmaildirectory, that that starts with
Once you determine which tarball to use for the source install and extract it, the
/usr/local/cpanel/bin/update-squirrelmailscript 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
$sqversionvariable must match the version number that the
Install SquirrelMail plugins
To enable a SquirrelMail plugin, perform the following steps:
/usr/local/cpanel/base/3rdparty/squirrelmail/config/conf.plcommand to open the SquirrelMail Configuration menu.
Enter the number of the
Pluginsoption. 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
Enter the number of the plugin that you wish to install.
Save your changes and exit the SquirrelMail Configuration menu.
To test your new SquirrelMail configuration, navigate to
example.com represents your domain name, and
sessionid represents your current security token.
Before you run the configuration test for SquirrelMail from a remote server, you must add the following line to the
$allow_remote_configtest = true;