This chapter discusses upgrading an existing SquirrelMail installation.
The system requirements may have been changed between your previous
version and this version of SquirrelMail. The requirements won't change
(much) between stable releases but may change significantly between
different series (e.g. between 1.2.x and 1.4.x). Most notably, you need
at least PHP version 4.1.0. The ReleaseNotes file is a good source for
information about changed requirements.
Also make sure to review the last section in this guide that details some issues that can arise if you are upgrading to or from certain versions.
Until you get your new version working right, you'll want to keep your
current version in place - you don't need to change it at all unless
you want to change its directory name to something like "squirrelmail-old"
to reduce confusion (in Linux-like environments, use a command like
"mv squirrelmail-1.4.8 squirrelmail-old").
In this guide, we'll assume your current version is installed in
/usr/share/squirrelmail-1.4.8 and that you'll be leaving it unchanged
(until the upgrade is complete).
Make sure that you are in the directory that contains your SquirrelMail
installation (in our exmaple, /usr/share/) and then unarchive the new
SquirrelMail version you just downloaded (in our example, we'll assume
you downloaded the squirrelmail-1.4.17.tar.gz distribution package;
unpacking any other package is very similar). In a Linux-like environment,
that would look like this:
$ cd /usr/share/ $ tar zxvf squirrelmail-1.4.17.tar.gz
Of course, this assumes you placed the new version you downloaded into the
/usr/share/ directory before you executed these commands. You should now
have a new directory called "squirrelmail-1.4.17" right next to your old
one (in this example "squirrelmail-1.4.8").
The important files to copy are:
If at all possible, start the configuration process from scratch. This way, you are much less prone to miss new configuration options or transfer any incompatible settings from one version to the next. That said, when upgrading between minor versions (e.g., within the 1.4 release series as in this example), copying your configuration files from the old installation to the new one should be perfectly acceptable. If you do so, it would be a good idea to run the configuration utility once as well as view the configuration test page to make sure that everything is OK.
Again, we'll start from the directory that contains your SquirrelMail installation(s), and these commands apply to Linux-like environments.
$ cd /usr/share/ $ cp -p squirrelmail-1.4.8/config/config.php squirrelmail-1.4.17/config/
If you have a local configuration file, copy that too:
$ cp -p squirrelmail-1.4.8/config/config_local.php squirrelmail-1.4.17/config/
As of version 1.5.2, you could copy the file plugin_hooks.php too, but
since this file is automatically generated, it is much better to run the
configuration utility once, save your settings and let SquirrelMail
create that file for you.
Like SquirrelMail, plugins are frequently updated with feature and security improvements as well as to make them compatible with new SquirrelMail releases. It is suggested that you download new versions of your plugins at the same time you download your SquirrelMail installation, and that you install your plugins fresh (it's easy, don't panic!).
PLEASE NOTE: You should not try to replace plugins that are already included in the SquirrelMail package. Sometimes third party plugins are brought into the SquirrelMail core, so take a peek at your new installation's plugins directory to see what is already there. You only need to download or copy your previous installation of third party plugins that are not in your new SquirrelMail package by default.
If you decide to copy plugin installations from your old installation, you can copy an entire plugin directory from the old installation to the new one (this example uses the Email Footer plugin):
$ cp -Rp squirrelmail-1.4.8/plugins/email_footer squirrelmail-1.4.17/plugins/
If you have configured any plugins so that their configuration files are
stored in the main SquirrelMail config/ directory, you'll want to copy
those files, too. Again, using the Email Footer example:
$ cp -p squirrelmail-1.4.8/config/config_email_footer.php squirrelmail-1.4.17/config/
Skins (template sets) are handled the same as plugins are (and are only part of SquirrelMail versions 1.5.2 and up). As skins are updated regularly, it's always best to just download and install the newest versions of your skins when you download your SquirrelMail upgrade package.
PLEASE NOTE: As with plugins, you should not try to replace skins that are already included in the SquirrelMail package. You only need to download or copy your previous installation of third party skins that are not in your new SquirrelMail package by default.
If you decide to copy skin installations from your old installation, you can copy an entire skin/template directory from the old installation to the new one (this example uses the Default Smarty skin pack):
$ cp -Rp squirrelmail-1.5.2/templates/default_smarty squirrelmail-1.5.3/templates/
Here again, we recommend that you simply download and install your
desired language translations from the newest locales pack on the
SquirrelMail website. If, however, you want to copy what you had
before, it's easiest to simply move the locale/ directory in the new
installation out of the way and copy the old one into its place:
$ mv squirrelmail-1.4.17/locale/ squirrelmail-1.4.17/locale-new $ cp -Rp squirrelmail-1.4.8/locale/ squirrelmail-1.4.17/
If you've created or modified themes, you should copy just those to the new
SquirrelMail themes directory:
$ cp -pi squirrelmail-1.4.8/themes/* squirrelmail-1.4.17/themes/
Chances are that, as long as you followed our installation recommendations,
you don't need to make any changes for your user preferences. That is,
if you have preferences stored in a database or you have moved your
preference file storage outside the SquirrelMail directory (such as
/var/lib/squirrelmail/data/) as explained in our installation documents,
then you don't need to do anything.
However, note that when upgrading between major versions (such as between 1.4.x and 1.5.x), it is usually best to create a secondary preferences storage location and start with a fresh system for your users to configure. That said, many preferences are the same between versions and to date there are no known incompatibilities between 1.4.x preferences and 1.5.x preferences.
If you have your preferences stored inside your old SquirrelMail
installation, we'd STRONGLY encourage you to re-read our installation
information and consider moving them away from the web server's reach.
If for some reason you need to continue to store your preferences inside
the SquirrelMail installation, you can move the new data/ directory out
of the way and copy the old preferences to the new installation:
$ mv squirrelmail-1.4.17/data/ squirrelmail-1.4.17/data-new $ cp -Rp squirrelmail-1.4.8/data/ squirrelmail-1.4.17/
If you are using Windows or otherwise cannot use the commands above, please
make sure that you preserve the permissions and ownership of the data/
directory as you move it, since SquirrelMail will not work unless the web
server has write permission in the data directory (which, presumably, your
old data directory has been set up with).
PLEASE NOTE: If you are upgrading from versions lower than 1.0.5, you are STRONGLY encouraged NOT to migrate preferences, since there were important security upgrades in the preferences system starting with SquirrelMail version 1.0.5.
Although not strictly necessary for minor upgrades, we STRONGLY
recommend that you run config/conf.pl to see the new
configuration options available with the new version, as well as
to verify that all of your old options are set properly. In SquirrelMail
versions 1.5.2 and above, this also ensures that your plugins are
properly registered with SquirrelMail.
Always save your options, even if you haven't changed anything. This will ensure that any problems with your configuration that have been automatically detected and fixed are not lost.
If you want to make sure that your configuration contains all themes included in new SquirrelMail package, go to theme options in configuration utility and run theme detection command.
You should browse to http://example.com/squirrelmail/src/configtest.php
(adjust the address to suit your system) and confirm that there are no
configuration problems. Note that in versions 1.5.0 and up, if you are
accessing configtest.php from any place other than the machine where
SquirrelMail is installed, you'll need to make sure
$allow_remote_configtest is enabled in your configuration file to do so
(or see "11. Tweaks" ==> "7. Allow remote configtest" in
the configuration utility). If you do that, be sure to disable it again when
you are finished.
Log in and take a look around in your new installation and make sure everything is working as expected.
Once you've finished upgrading, you may want to keep an archived copy of your old installation just in case something goes wrong with the new one. You can simply move the whole directory somewhere else outside of your web server's document root or compress the directory into an archive file for storage elsewhere. Here's how to create a zip file of your old installation in a Linux-like environment:
$ cd /usr/share/ $ zip -r squirrelmail-1.4.8.zip squirrelmail-1.4.8
Or to create a gzipped tar archive:
$ tar czvf squirrelmail-1.4.8.tar.gz squirrelmail-1.4.8
Then make sure that you REMOVE the old directory so users can no longer access it - if you don't do this, you may be leaving yourself exposed to known security exploits.
In this guide, we assumed that your installation directories looked
like "squirrelmail-1.4.17". Most of the time, you'll want to allow
your users to type in "squirrelmail" (or just "webmail"
or "mail") without needing to know the version number. Of course,
you can simply change the name of the SquirrelMail installation directory:
$ cd /usr/share/ $ mv squirrelmail-1.4.17 mail
... but there are several more graceful ways you can achieve this. In any Linux-like system, you can use symlinks to dynamically point "webmail" to any of your version-specific installations:
$ cd /usr/share/ $ ln -s squirrelmail-1.4.17 mail
Note that symlinks can point anywhere you need them to, so the installation
directory doesn't necessarily need to be in the same place the "mail" link
is.
You can also configure most any web server to point to your installation directory from any incoming address you desire. There are several redirection and address re-writing tools for most web servers, so this is just one example using Apache's Redirect directive:
Redirect permanent /squirrelmail-1.4.17 https://example.com/mail
The plugin API changed substantially in version 1.5.2. At the least, you should NOT copy your old plugins when making this kind of upgrade.
Due to a fix made that standardizes the folder list display, administrators who had their configuration file set to work around this issue in the past will need to update their configuration. This will commonly affect those using Courier IMAP, but could affect others as well.
If you have $default_sub_of_inbox set to FALSE in your main
configuration (or, using the configuration tool, see "3. Folder Defaults"
===> "12. Default Sub. of INBOX"), and you find after upgrade that your
special folders (e.g., Trash, Drafts, Sent) are no longer listed at the top of
your folder list, please change that value to TRUE.
Also, if you find that this upgrade prevents users from logging in with an
error such as "ERROR: Could not complete request. Query: CREATE "Trash"
Reason Given: Invalid mailbox name.", you will need to correct the user
preference values for the problem folders. You can do so with commands such
as the following for file-based preferences (adjust the data directory location
as needed):
find /var/lib/squirrelmail/data/ -name *.pref -exec sed --in-place 's/trash_folder=Trash/trash_folder=INBOX.Trash/g' {} \;
find /var/lib/squirrelmail/data/ -name *.pref -exec sed --in-place 's/draft_folder=Drafts/draft_folder=INBOX.Drafts/g' {} \;
find /var/lib/squirrelmail/data/ -name *.pref -exec sed --in-place 's/sent_folder=Sent/sent_folder=INBOX.Sent/g' {} \;
Or, for database-based preferences:
UPDATE userprefs SET prefval = 'INBOX.Trash' WHERE prefkey = 'trash_folder' AND prefval = 'Trash';
UPDATE userprefs SET prefval = 'INBOX.Drafts' WHERE prefkey = 'draft_folder' AND prefval = 'Drafts';
UPDATE userprefs SET prefval = 'INBOX.Sent' WHERE prefkey = 'sent_folder' AND prefval = 'Sent';
MAKE SURE to back up your user preferences before doing any of the above!
Several layout changes were made and there were other changes that require plugin updates. At the least, you should NOT copy your old plugins when making this kind of upgrade.
Translations were removed from the main SquirrelMail package. Unless you copy the translations from your old installation, you will now need to visit the SquirrelMail download page and also get a copy of the our locales package.
The "Index Order" options and SquirrelSpell user dictionaries will not be
preserved if you use the same user preferences, although we discourage the
use of the same preference sets between major release numbers (e.g., 1.4.x
and 1.5.x).
The names used by some translations were changed starting in version 1.2.2.
In most cases, you won't see any problems due to this change, however,
the Norwegian Nynorsk (no_NO_ny) translation might need to be fixed. If
you decide to retain the same preferences from your old installation, any
users who have a "language" preference set to "no_NO_ny" will need to
have it manually changed to "nn_NO".
Some important security upgrades were made to the preferences system in version 1.0.5. It is NOT recommended that you retain user preferences when upgrading from versions older than 1.0.5.