[prev in list] [next in list] [prev in thread] [next in thread] 

List:       squirrelmail-cvs
Subject:    [SM-CVS] SF.net SVN: squirrelmail:[13482]
From:       pdontthink () users ! sourceforge ! net
Date:       2009-03-27 7:13:56
Message-ID: E1Ln6GK-0008N3-IQ () 74yxhf1 ! ch3 ! sourceforge ! com
[Download RAW message or body]

Revision: 13482
          http://squirrelmail.svn.sourceforge.net/squirrelmail/?rev=13482&view=rev
Author:   pdontthink
Date:     2009-03-27 07:13:56 +0000 (Fri, 27 Mar 2009)

Log Message:
-----------
Update the upgrade section, synchronized with the doc/UPGRADE document in the stable \
and devel code branches.  If you make changes to that section in the future, please \
remember to also update those to documents as well.

Modified Paths:
--------------
    trunk/documentation/admin/admin.sgml

Modified: trunk/documentation/admin/admin.sgml
===================================================================
--- trunk/documentation/admin/admin.sgml	2009-03-27 04:28:36 UTC (rev 13481)
+++ trunk/documentation/admin/admin.sgml	2009-03-27 07:13:56 UTC (rev 13482)
@@ -811,180 +811,337 @@
 
 <sect>Upgrading SquirrelMail
 <p>
-This chapter talks about upgrading an existing SquirrelMail install.
+This chapter discusses upgrading an existing SquirrelMail installation.
 
-<sect1>Backup old install
+<sect1>Check requirements
 <p>
-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.
+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 <tt/ReleaseNotes/ file is a good source for
+information about changed requirements.
 
-In this example, we assume that your httpd document directory is
-<tt>/home/httpd/html</tt>, that your SquirrelMail install is located at
-<tt>/home/httpd/html/squirrelmail-1.0.6</tt>, and that your new SquirrelMail
-version is 1.2.0. Substitute version numbers and names as required.
+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.
 
-<verb>
-$ cd /home/httpd/html
-$ cp -Rp squirrelmail-1.0.6 squirrelmail-1.0.6.bak
-</verb>
+<sect1>What to do with your old installation
+<p>
+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 "<tt/squirrelmail-old/"
+to reduce confusion (in Linux-like environments, use a command like
+"<tt>mv squirrelmail-1.4.8 squirrelmail-old</tt>").
 
+In this guide, we'll assume your current version is installed in
+<tt>/usr/share/squirrelmail-1.4.8</tt> and that you'll be leaving it unchanged
+(until the upgrade is complete).
+
 <sect1>Unpack new SquirrelMail
 <p>
-Make sure that you are in your httpd document directory (<tt>/home/httpd/html</tt>)
-and then unpack the SquirrelMail archive (whatever the filename is):
+Make sure that you are in the directory that contains your SquirrelMail
+installation (in our exmaple, <tt>/usr/share/</tt>) and then unarchive the new
+SquirrelMail version you just downloaded (in our example, we'll assume
+you downloaded the <tt>squirrelmail-1.4.17.tar.gz</tt> distribution package;
+unpacking any other package is very similar).  In a Linux-like environment,
+that would look like this:
+
 <verb>
-$ tar -zxvf squirrelmail-1.2.0.tar.gz
+  $ cd /usr/share/
+  $ tar zxvf squirrelmail-1.4.17.tar.gz
 </verb>
 
-<sect1>Copy important files from old install
+Of course, this assumes you placed the new version you downloaded into the
+<tt>/usr/share/</tt> directory before you executed these commands.  You should now
+have a new directory called "<tt>squirrelmail-1.4.17</tt>" right next to your old
+one (in this example "<tt>squirrelmail-1.4.8</tt>").
+
+<sect1>Copy important files from old installation
 <p>
 The important files to copy are:
 <itemize>
-  <item>Preferences
-  <item>Config details
+  <item>Configuration files
   <item>Plugins
+  <item>Skins
+  <item>Translations
   <item>Themes (if you've edited or added any of them)
+  <item>Preferences (but only if you keep them inside the SquirrelMail directory)
 </itemize>
 
-<sect2>Preferences
+<sect2>Configuration files
 <p>
-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.
+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.
+  
 <verb>
-$ cp squirrelmail-1.0.6.bak/data/* squirrelmail-1.2.0/data
+  $ cd /usr/share/
+  $ cp -p squirrelmail-1.4.8/config/config.php squirrelmail-1.4.17/config/
 </verb>
 
-<sect2>Config details
+If you have a local configuration file, copy that too:
+  
+<verb>
+  $ cp -p squirrelmail-1.4.8/config/config_local.php squirrelmail-1.4.17/config/
+</verb>
+
+As of version 1.5.2, you could copy the file <tt/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.
+
+<sect2>Plugins
 <p>
-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.
+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):
+  
 <verb>
-$ cp squirrelmail-1.0.6.bak/config/config.php squirrelmail-1.2.0/config
+  $ cp -Rp squirrelmail-1.4.8/plugins/email_footer squirrelmail-1.4.17/plugins/
 </verb>
 
-<sect2>Copy plugins
+If you have configured any plugins so that their configuration files are
+stored in the main SquirrelMail <tt>config/</tt> directory, you'll want to copy
+those files, too.  Again, using the Email Footer example:
+  
+<verb>
+  $ cp -p squirrelmail-1.4.8/config/config_email_footer.php \
squirrelmail-1.4.17/config/ +</verb>
+
+<sect2>Skins
 <p>
-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!).
+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.
 
-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.
+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.
 
-<sect2>Copy themes
+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):
+
+<verb>
+  $ cp -Rp squirrelmail-1.5.2/templates/default_smarty squirrelmail-1.5.3/templates/
+</verb>
+
+<sect2>Translations
 <p>
-TODO: this changes in 1.5.2
+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 <tt>locale/</tt> directory in the new
+installation out of the way and copy the old one into its place:
 
+<verb>
+  $ mv squirrelmail-1.4.17/locale/ squirrelmail-1.4.17/locale-new
+  $ cp -Rp squirrelmail-1.4.8/locale/ squirrelmail-1.4.17/
+</verb>
+
+<sect2>Themes
+<p>
 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 <tt>themes</tt> directory:
+
 <verb>
-$ cp -ui squirrelmail-1.0.6.bak/themes/* squirrelmail-1.2.0/themes/
+  $ cp -pi squirrelmail-1.4.8/themes/* squirrelmail-1.4.17/themes/
 </verb>
 
-When <tt/-u/ flag is used, command copies only missing and newer files.
-When <tt/-i/ flag is used, command will ask for confirmation before replacing
-existing files.
+<sect2>Preferences
+<p>
+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
+<tt>/var/lib/squirrelmail/data/</tt>) as explained in our installation documents,
+then you don't need to do anything.
 
-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!
+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.
 
-<sect1>Change permissions
-<p>
-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.
+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 <tt>data/</tt> directory out
+of the way and copy the old preferences to the new installation:
+
 <verb>
-  $ cd squirrelmail-1.2.0
-  $ chown -R nobody:nobody data
+  $ mv squirrelmail-1.4.17/data/ squirrelmail-1.4.17/data-new
+  $ cp -Rp squirrelmail-1.4.8/data/ squirrelmail-1.4.17/
 </verb>
 
-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 Windows or otherwise cannot use the commands above, please
+make sure that you preserve the permissions and ownership of the <tt>data/</tt>
+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).
 
-If you are using SquirrelMail in setup with PHP <tt/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 <ref
-id="safe_mode" name="Safe mode">).
+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.
 
-<sect1>Run conf.pl
+<sect1>Run the configuration utility
 <p>
-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.
+Although not strictly necessary for minor upgrades, we STRONGLY
+recommend that you run <tt>config/conf.pl</tt> 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, 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.
+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.
+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.
 
-<sect1>Version specific notes
-<sect2>Upgrade from version older than 1.2.2 to later version.
+<sect1>Visit src/configtest.php
 <p>
-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 <tt/language=no_NO_ny/ lines, these lines
-should be updated to <tt/language=nn_NO/.
+You should browse to <tt>http://example.com/squirrelmail/src/configtest.php</tt>
+(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 <tt>$allow_remote_configtest</tt> is enabled in your configuration
+file to do so (or see "<tt>11. Tweaks</tt>" ==> "<tt>7. Allow remote \
configtest</tt>" in +the configuration utility).
 
-<sect2>Upgrade from 1.2.x or older versions to 1.4.x or later.
+<sect1>Verify that the new installation works
 <p>
-Layout changes. Plugins can break.
+Log in and take a look around in your new installation and make sure
+everything is working as expected.
 
-<sect2>Upgrade from version older than 1.4.4 to later version.
+<sect1>Follow-up
 <p>
-Translations are removed in order to reduce package size. You must download
-and install separate translation packages.
+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:
 
-<sect2>Downgrade from 1.5.1 to older version.
-<p>
-Index Order options are not preserved.
+<verb>
+  $ cd /usr/share/
+  $ zip -r squirrelmail-1.4.8.zip squirrelmail-1.4.8
+</verb>
 
-SquirrelSpell user dictionaries are not preserved.
+Or to create a gzipped tar archive:
 
-<sect1>Recheck new install
-<p>
-Login into new SquirrelMail install and check if everything is working.
+<verb>
+  $ tar czvf squirrelmail-1.4.8.tar.gz squirrelmail-1.4.8
+</verb>
 
-<sect1>Replace old install.
+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.
+
+<sect1>How to point the web server to different SquirrelMail installations
 <p>
-Redirect your users to new SquirrelMail install. You can use Apache <url
-url="http://httpd.apache.org/docs/mod/mod_alias.html#redirectperm"
-name="RedirectPermanent"> directive or other redirection tools provided by your
-webserver.
+In this guide, we assumed that your installation directories looked
+like "<tt>squirrelmail-1.4.17</tt>".  Most of the time, you'll want to allow
+your users to type in "<tt>squirrelmail</tt>" (or just "<tt>webmail</tt>" or \
"<tt>mail</tt>") +without needing to know the version number.  Of course, you can \
simply +change the name of the SquirrelMail installation directory:
 
-If you use SquirrelMail directory without version information, you can also
-replace it with new SquirrelMail directory.
 <verb>
-$ mv /home/httpd/html/squirrelmail /home/httpd/html/squirrelmail.old
-$ mv /home/httpd/html/squirrelmail.new /home/httpd/html/squirrelmail
+  $ cd /usr/share/
+  $ mv squirrelmail-1.4.8 mail
 </verb>
 
-<sect1>DONE!
+... 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:
+
+<verb>
+  $ cd /usr/share/
+  $ ln -s squirrelmail-1.4.8 mail
+</verb>
+
+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 "<tt>mail</tt>" 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:
+
+<verb>
+  Redirect permanent  /squirrelmail-1.4.17  https://example.com/mail
+</verb>
+
+<sect1>Version-specific upgrade issues
+
+<sect2>Upgrading from the 1.4 release series to the 1.5 release series
 <p>
-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.
+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.
 
+<sect2>Upgrading from the 1.2 release series to the 1.4 release series
+<p>
+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.
+
+<sect2>Upgrading from any version older than 1.4.4 to version 1.4.4 or later
+<p>
+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.
+
+<sect2>Downgrading from version 1.5.1 to any version older than 1.5.1
+<p>
+The "<tt>Index Order</tt>" 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).
+
+<sect2>Upgrading from any version older than 1.2.2 to version 1.2.2 or later
+<p>
+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 (<tt>no_NO_ny</tt>) translation might need to be fixed.  If
+you decide to retain the same preferences from your old installation, any
+users who have a "<tt>language</tt>" preference set to "<tt>no_NO_ny</tt>" will need \
to +have it manually changed to "<tt>nn_NO</tt>".
+
+<sect2>Upgrading from any version older than 1.0.5 to version 1.0.5 or later
+<p>
+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.
+
 <sect>Configuring SquirrelMail<label id="configuring">
 <p>
 Even though the size of this documentation might indicate otherwise,


This was sent by the SourceForge.net collaborative development platform, the world's \
largest Open Source development site.

------------------------------------------------------------------------------
-----
squirrelmail-cvs mailing list
List address: squirrelmail-cvs@lists.sourceforge.net
List info (subscribe/unsubscribe/change options): \
                https://lists.sourceforge.net/lists/listinfo/squirrelmail-cvs
Repository: http://squirrelmail.org/svn


[prev in list] [next in list] [prev in thread] [next in thread]