X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=doc%2FUPGRADE;h=c7b38b8cb33fcada941ee709577adc7caa9efd13;hb=2131e73eac2f52fcfef5015a4632dffc4226ee90;hp=810a9dd13e4f07e7e7bf5dc78488624276e1e277;hpb=146ccfe73cd403061918238b3b53b3d0521bcb0e;p=squirrelmail.git diff --git a/doc/UPGRADE b/doc/UPGRADE index 810a9dd1..c7b38b8c 100644 --- a/doc/UPGRADE +++ b/doc/UPGRADE @@ -1,123 +1,341 @@ -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. + +B. Plugins +----------- -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. +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!). - $ cp squirrelmail-1.2.6.bak/data/* squirrelmail-1.4.0/data +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. -B. Config details +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): -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 -Rp squirrelmail-1.4.8/plugins/email_footer squirrelmail-1.4.17/plugins/ - $ cp squirrelmail-1.2.6.bak/config/config.php squirrelmail-1.4.0/config +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: -C. Copy plugins + $ cp -p squirrelmail-1.4.8/config/config_email_footer.php squirrelmail-1.4.17/config/ -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!). +C. Skins +--------- -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. +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. -D. Copy themes +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 -pi squirrelmail-1.4.8/themes/* squirrelmail-1.4.17/themes/ + + +F. Preferences +--------------- + +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. + +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. + +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/ + +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 for minor upgrades, 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. 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. + + +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 the 1.4 release series to the 1.5 release series +--------------------------------------------------------------- + +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. - $ cp -ui squirrelmail-1.2.6.bak/themes/* squirrelmail-1.4.0/themes/ +Upgrading from the 1.2 release series to the 1.4 release series +--------------------------------------------------------------- -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. +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 +--------------------------------------------------------------------- -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. +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. - $ cd squirrelmail-1.4.0 - $ chown -R nobody:nobody data +Downgrading from version 1.5.1 to any version older than 1.5.1 +-------------------------------------------------------------- -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. +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). +Upgrading from any version older than 1.2.2 to version 1.2.2 or later +--------------------------------------------------------------------- -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. +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". -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. +Upgrading from any version older than 1.0.5 to version 1.0.5 or later +--------------------------------------------------------------------- +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. -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.