Menu
▾
▴
[SM-CVS] SF.net SVN: squirrelmail:[13482] trunk/documentation/admin/admin.sgml
|
From: <pdo...@us...> - 2009-03-27 07:14:08
|
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.
|