Upgrade manual was aging and needed to be synchronized to that in the stable tree...
authorpdontthink <pdontthink@7612ce4b-ef26-0410-bec9-ea0150e637f0>
Fri, 27 Mar 2009 03:56:29 +0000 (03:56 +0000)
committerpdontthink <pdontthink@7612ce4b-ef26-0410-bec9-ea0150e637f0>
Fri, 27 Mar 2009 03:56:29 +0000 (03:56 +0000)
git-svn-id: https://svn.code.sf.net/p/squirrelmail/code/trunk/squirrelmail@13475 7612ce4b-ef26-0410-bec9-ea0150e637f0

doc/UPGRADE

index 810a9dd13e4f07e7e7bf5dc78488624276e1e277..8ccb2454ff052a1d462cd6b48355a320ed9fdd8f 100644 (file)
-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.