-Upgrading from 0.3 or higher
-============================
+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.
-If you are upgrading from versions 0.3 or higher of SquirrelMail, you can
-use this guide to make the transition a bit smoother. If you have been
-using a previous version (0.1 or 0.2), it is suggested that you just start
-from scratch and configure your settings as if it was your first install.
-NOTE: The new plugin architecture required the use of some functions which
-are not in all versions of PHP. You will need at least PHP 4.1.0. If you
-need to upgrade please go ahead and install the latest release version of
-PHP.
+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.
-1. Backup old install
-======================
+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.
-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.2.6, and that your new SM version is 1.4.0.
-Substitute version numbers and names as required.
+1. What to do with your old installation
+=========================================
- $ cd /home/httpd/html
- $ cp -Rp squirrelmail-1.2.6 squirrelmail-1.2.6.bak
+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. Unarchive new SquirrelMail
-==============================
-Make sure that you are in your httpd document directory (/home/httpd/html)
-and then unarchive the SquirrelMail archive (whatever the filename is):
- $ tar -zxvf squirrelmail-1.4.0.tar.gz
+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
+==============================================
-3. Copy important files from old install
-=========================================
The important files to copy are:
- A. Preferences
- B. Config details
- C. Plugins
- D. Themes (if you've edited or added any of them)
-A. Preferences
+ 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.
-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.
+B. Plugins
+-----------
- $ cp squirrelmail-1.2.6.bak/data/* squirrelmail-1.4.0/data
+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!).
-B. Config details
+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 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.
+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 squirrelmail-1.2.6.bak/config/config.php squirrelmail-1.4.0/config
+ $ cp -Rp squirrelmail-1.4.8/plugins/email_footer squirrelmail-1.4.17/plugins/
-C. Copy 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:
-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!).
+ $ cp -p squirrelmail-1.4.8/config/config_email_footer.php squirrelmail-1.4.17/config/
-You should not try replacing plugins that are already included in SquirrelMail
-package. Download latest versions of plugins that are not included in new
-SquirrelMail package or copy them from older SquirrelMail install.
+C. Skins
+---------
-D. Copy themes
+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. To just copy them all over to the new
-SquirrelMail installation, you can run one command.
+SquirrelMail themes directory:
- $ cp -ui squirrelmail-1.2.6.bak/themes/* squirrelmail-1.4.0/themes/
+ $ cp -pi squirrelmail-1.4.8/themes/* squirrelmail-1.4.17/themes/
-When -u flag is used, command copies only missing and newer files.
-When -i flag is used, command asks for confirmation before replacing
-existing files.
+F. Preferences
+---------------
-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.
+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.
- $ cd squirrelmail-1.4.0
- $ chown -R nobody:nobody data
+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.
-See INSTALL for alternate userid/groupid pairs. 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 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/
-5. Run conf.pl
-===============
-Run config/conf.pl to see the new configuration options available with the
+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, 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.
+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. Of course, don't remove it yet - that's
+your last step after you've been able to make your new installation work.
+
+
+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 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 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.
-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.
+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).
-6. 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.
projects / squirrelmail.git / commitdiff