341 lines
14 KiB
Text
341 lines
14 KiB
Text
Upgrading your SquirrelMail Installation
|
|
========================================
|
|
|
|
If you are upgrading from a previous version of SquirrelMail, you can
|
|
use this guide to make the transition a bit smoother.
|
|
|
|
|
|
0. Check requirements
|
|
=====================
|
|
|
|
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.
|
|
|
|
|
|
1. What to do with your old installation
|
|
=========================================
|
|
|
|
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).
|
|
|
|
|
|
2. Unpack new SquirrelMail
|
|
===========================
|
|
|
|
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").
|
|
|
|
|
|
3. Copy important files from old installation
|
|
==============================================
|
|
|
|
The important files to copy are:
|
|
|
|
A. Configuration files
|
|
B. Plugins
|
|
C. Skins
|
|
D. Translations
|
|
E. Themes (if you've edited or added any of them)
|
|
F. Preferences (but only if you keep them inside the
|
|
SquirrelMail directory)
|
|
|
|
A. Configuration files
|
|
-----------------------
|
|
|
|
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.
|
|
|
|
B. Plugins
|
|
-----------
|
|
|
|
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/
|
|
|
|
C. Skins
|
|
---------
|
|
|
|
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/
|
|
|
|
D. Translations
|
|
----------------
|
|
|
|
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/
|
|
|
|
|
|
E. Themes
|
|
----------
|
|
|
|
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/
|
|
|
|
|
|
F. Preferences
|
|
---------------
|
|
|
|
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.
|
|
|
|
|
|
4. Run the configuration utility
|
|
=================================
|
|
|
|
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.
|
|
|
|
|
|
5. Visit src/configtest.php
|
|
============================
|
|
|
|
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, 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).
|
|
|
|
|
|
6. Verify that the new installation works
|
|
==========================================
|
|
|
|
Log in and take a look around in your new installation and make sure
|
|
everything is working as expected.
|
|
|
|
|
|
7. Follow-up
|
|
=============
|
|
|
|
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.
|
|
|
|
|
|
8. How to point the web server to different SquirrelMail installations
|
|
======================================================================
|
|
|
|
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.8 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.8 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
|
|
|
|
|
|
9. Version-specific upgrade issues
|
|
==================================
|
|
|
|
Upgrading from the 1.4 release series to the 1.5 release series
|
|
---------------------------------------------------------------
|
|
|
|
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.
|
|
|
|
Upgrading from the 1.2 release series to the 1.4 release series
|
|
---------------------------------------------------------------
|
|
|
|
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.
|
|
|
|
Upgrading from any version older than 1.4.4 to version 1.4.4 or later
|
|
---------------------------------------------------------------------
|
|
|
|
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.
|
|
|
|
Downgrading from version 1.5.1 to any version older than 1.5.1
|
|
--------------------------------------------------------------
|
|
|
|
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).
|
|
|
|
Upgrading from any version older than 1.2.2 to version 1.2.2 or later
|
|
---------------------------------------------------------------------
|
|
|
|
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".
|
|
|
|
Upgrading from any version older than 1.0.5 to version 1.0.5 or later
|
|
---------------------------------------------------------------------
|
|
|
|
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.
|
|
|