4. Upgrading SquirrelMail

This chapter talks about upgrading an existing SquirrelMail install.

4.1 Backup old install

Make a backup of your current SquirrelMail directory. If you use "cp", be sure to use the "-Rp" options. -R means recursive, and -p will save the permissions in the directory.

In this example, we assume that your httpd document directory is /home/httpd/html, that your SquirrelMail install is located at /home/httpd/html/squirrelmail-1.0.6, and that your new SquirrelMail version is 1.2.0. Substitute version numbers and names as required.

$ cd /home/httpd/html
$ cp -Rp squirrelmail-1.0.6 squirrelmail-1.0.6.bak

4.2 Unpack new SquirrelMail

Make sure that you are in your httpd document directory (/home/httpd/html) and then unpack the SquirrelMail archive (whatever the filename is):

$ tar -zxvf squirrelmail-1.2.0.tar.gz

4.3 Copy important files from old install

The important files to copy are:

• Preferences
• Config details
• Plugins
• Themes (if you've edited or added any of them)

Preferences

First, copy your preference data over to the new directory. Usually this is ok, but if you are upgrading from anything less than 1.0.5, we strongly suggest you let your users reset their preferences. There were important security upgrades in 1.0.5 regarding preference files.

$ cp squirrelmail-1.0.6.bak/data/* squirrelmail-1.2.0/data

Config details

If at all possible, start the configuration process from scratch. It is much less prone to missing configuration options than copying your old configuration. Ideally, you should just run conf.pl to reconfigure SquirrelMail. If you decide to copy your old config.php over, we strongly recommend that you run conf.pl to make sure things are correct and then save the config file.

$ cp squirrelmail-1.0.6.bak/config/config.php squirrelmail-1.2.0/config

Copy plugins

Like SquirrelMail, plugins are frequently updated for 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 install, and that you install your plugins fresh (it's easy, don't panic!).

You should not try replacing plugins that are already included in the SquirrelMail package. Download latest versions of plugins that are not included in the new SquirrelMail package or copy them from your older SquirrelMail install.

Copy themes

TODO: this changes in 1.5.2

If you've created or modified themes, you should copy just those to the new SquirrelMail themes directory. To just copy them all over to the new SquirrelMail installation, you can run one command.

$ cp -ui squirrelmail-1.0.6.bak/themes/* squirrelmail-1.2.0/themes/

When -u flag is used, command copies only missing and newer files. When -i flag is used, command will ask for confirmation before replacing existing files.

If you want to see your theme in future SquirrelMail packages, send it to SquirrelMail developers. They might add it to the themes in the standard install!

4.4 Change permissions

The web server must have write permission to the data directory. In this example, we assume that user "nobody" and group "nobody" are the web server as is often the case with Apache.

  $ cd squirrelmail-1.2.0
  $ chown -R nobody:nobody data

Check your webserver's configuration file. It might be using different userid/groupid pair. Additionally, if "chown user:group" doesn't work, you can use "chown user" and "chgrp group" instead. See the man pages for these commands for more information.

If you are using SquirrelMail in setup with PHP safe_mode restrictions, data and attachment directories should be owned by same user that owns other SquirrelMail scripts. It must be writable by the web server group (see Safe mode).

4.5 Run conf.pl

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.

Always save your options, also if you haven't changed anything. This will ensure that any problems with conf.pl that might have been solved are effective to your installation.

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.

4.6 Version specific notes

Upgrade from version older than 1.2.2 to later version.

In order to provide better internationalization support, developers have changed names used by translations. From 1.2.2 SquirrelMail uses language and country codes in translation names. In most of cases upgraded SquirrelMail should work correctly. Only Norwegian Nynorsk (no_NO_ny) translation might need fixes. If your user preference files contain language=no_NO_ny lines, these lines should be updated to language=nn_NO.

Upgrade from 1.2.x or older versions to 1.4.x or later.

Layout changes. Plugins can break.

Upgrade from version older than 1.4.4 to later version.

Translations are removed in order to reduce package size. You must download and install separate translation packages.

Downgrade from 1.5.1 to older version.

Index Order options are not preserved.

SquirrelSpell user dictionaries are not preserved.

4.7 Recheck new install

Login into new SquirrelMail install and check if everything is working.

4.8 Replace old install.

Redirect your users to new SquirrelMail install. You can use Apache RedirectPermanent directive or other redirection tools provided by your webserver.

If you use SquirrelMail directory without version information, you can also replace it with new SquirrelMail directory.

$ mv /home/httpd/html/squirrelmail /home/httpd/html/squirrelmail.old
$ mv /home/httpd/html/squirrelmail.new /home/httpd/html/squirrelmail

4.9 DONE!

That should be all! The most important part is copying your users' preference files back into the new data directory. This will insure that your users will have their old preferences. Remember to do so with caution, especially if you are upgrading from a version before 1.0.5 to version 1.0.5 or later.