Now properly quote personal part of encoded addresses when replying
[squirrelmail.git] / doc / UPGRADE
CommitLineData
494d3adb 1Upgrading your SquirrelMail Installation
2========================================
3
4If you are upgrading from a previous version of SquirrelMail, you can
5use this guide to make the transition a bit smoother.
47f9c368 6
f4057b81 7
494d3adb 80. Check requirements
9=====================
f4057b81 10
494d3adb 11The system requirements may have been changed between your previous
12version and this version of SquirrelMail. The requirements won't change
13(much) between stable releases but may change significantly between
14different series (e.g. between 1.2.x and 1.4.x). Most notably, you need
15at least PHP version 4.1.0. The ReleaseNotes file is a good source for
16information about changed requirements.
8462c882 17
494d3adb 18Also make sure to review the last section in this guide that details
19some issues that can arise if you are upgrading to or from certain
20versions.
2b996daf 21
8462c882 22
494d3adb 231. What to do with your old installation
24=========================================
f4057b81 25
494d3adb 26Until you get your new version working right, you'll want to keep your
27current version in place - you don't need to change it at all unless
28you want to change its directory name to something like "squirrelmail-old"
29to reduce confusion (in Linux-like environments, use a command like
30"mv squirrelmail-1.4.8 squirrelmail-old").
f4057b81 31
494d3adb 32In this guide, we'll assume your current version is installed in
33/usr/share/squirrelmail-1.4.8 and that you'll be leaving it unchanged
34(until the upgrade is complete).
f4057b81 35
2b996daf 36
494d3adb 372. Unpack new SquirrelMail
38===========================
f4057b81 39
494d3adb 40Make sure that you are in the directory that contains your SquirrelMail
41installation (in our exmaple, /usr/share/) and then unarchive the new
42SquirrelMail version you just downloaded (in our example, we'll assume
43you downloaded the squirrelmail-1.4.17.tar.gz distribution package;
44unpacking any other package is very similar). In a Linux-like environment,
45that would look like this:
46
47 $ cd /usr/share/
48 $ tar zxvf squirrelmail-1.4.17.tar.gz
49
50Of course, this assumes you placed the new version you downloaded into the
51/usr/share/ directory before you executed these commands. You should now
52have a new directory called "squirrelmail-1.4.17" right next to your old
53one (in this example "squirrelmail-1.4.8").
54
55
563. Copy important files from old installation
57==============================================
f4057b81 58
8462c882 59The important files to copy are:
b8aaaa7b 60
494d3adb 61 A. Configuration files
62 B. Plugins
63 C. Skins
64 D. Translations
65 E. Themes (if you've edited or added any of them)
66 F. Preferences (but only if you keep them inside the
67 SquirrelMail directory)
68
69A. Configuration files
70-----------------------
71
72If at all possible, start the configuration process from scratch. This
73way, you are much less prone to miss new configuration options or transfer
74any incompatible settings from one version to the next. That said, when
75upgrading between minor versions (e.g., within the 1.4 release series as
76in this example), copying your configuration files from the old installation
77to the new one should be perfectly acceptable. If you do so, it would be
78a good idea to run the configuration utility once as well as view the
79configuration test page to make sure that everything is OK.
80
81Again, we'll start from the directory that contains your SquirrelMail
82installation(s), and these commands apply to Linux-like environments.
83
84 $ cd /usr/share/
85 $ cp -p squirrelmail-1.4.8/config/config.php squirrelmail-1.4.17/config/
86
87If you have a local configuration file, copy that too:
88
89 $ cp -p squirrelmail-1.4.8/config/config_local.php squirrelmail-1.4.17/config/
90
91As of version 1.5.2, you could copy the file plugin_hooks.php too, but
92since this file is automatically generated, it is much better to run the
93configuration utility once, save your settings and let SquirrelMail
94create that file for you.
f4057b81 95
494d3adb 96B. Plugins
97-----------
b8aaaa7b 98
494d3adb 99Like SquirrelMail, plugins are frequently updated with feature and security
100improvements as well as to make them compatible with new SquirrelMail
101releases. It is suggested that you download new versions of your plugins at
102the same time you download your SquirrelMail installation, and that you
103install your plugins fresh (it's easy, don't panic!).
b8aaaa7b 104
494d3adb 105PLEASE NOTE: You should not try to replace plugins that are already included
106in the SquirrelMail package. Sometimes third party plugins are brought into
107the SquirrelMail core, so take a peek at your new installation's plugins
108directory to see what is already there. You only need to download or copy
109your previous installation of third party plugins that are not in your new
110SquirrelMail package by default.
8462c882 111
494d3adb 112If you decide to copy plugin installations from your old installation, you
113can copy an entire plugin directory from the old installation to the new
114one (this example uses the Email Footer plugin):
8462c882 115
494d3adb 116 $ cp -Rp squirrelmail-1.4.8/plugins/email_footer squirrelmail-1.4.17/plugins/
f4057b81 117
494d3adb 118If you have configured any plugins so that their configuration files are
119stored in the main SquirrelMail config/ directory, you'll want to copy
120those files, too. Again, using the Email Footer example:
8462c882 121
494d3adb 122 $ cp -p squirrelmail-1.4.8/config/config_email_footer.php squirrelmail-1.4.17/config/
8462c882 123
494d3adb 124C. Skins
125---------
b8aaaa7b 126
494d3adb 127Skins (template sets) are handled the same as plugins are (and are only
128part of SquirrelMail versions 1.5.2 and up). As skins are updated regularly,
129it's always best to just download and install the newest versions of your
130skins when you download your SquirrelMail upgrade package.
131
132PLEASE NOTE: As with plugins, you should not try to replace skins that are
133already included in the SquirrelMail package. You only need to download or
134copy your previous installation of third party skins that are not in your
135new SquirrelMail package by default.
136
137If you decide to copy skin installations from your old installation, you
138can copy an entire skin/template directory from the old installation to the
139new one (this example uses the Default Smarty skin pack):
140
141 $ cp -Rp squirrelmail-1.5.2/templates/default_smarty squirrelmail-1.5.3/templates/
142
143D. Translations
144----------------
145
146Here again, we recommend that you simply download and install your
147desired language translations from the newest locales pack on the
148SquirrelMail website. If, however, you want to copy what you had
149before, it's easiest to simply move the locale/ directory in the new
150installation out of the way and copy the old one into its place:
151
152 $ mv squirrelmail-1.4.17/locale/ squirrelmail-1.4.17/locale-new
153 $ cp -Rp squirrelmail-1.4.8/locale/ squirrelmail-1.4.17/
154
155
156E. Themes
157----------
8462c882 158
159If you've created or modified themes, you should copy just those to the new
494d3adb 160SquirrelMail themes directory:
8462c882 161
494d3adb 162 $ cp -pi squirrelmail-1.4.8/themes/* squirrelmail-1.4.17/themes/
3fe751d7 163
8462c882 164
494d3adb 165F. Preferences
166---------------
f4057b81 167
494d3adb 168Chances are that, as long as you followed our installation recommendations,
169you don't need to make any changes for your user preferences. That is,
170if you have preferences stored in a database or you have moved your
171preference file storage outside the SquirrelMail directory (such as
172/var/lib/squirrelmail/data/) as explained in our installation documents,
173then you don't need to do anything.
f4057b81 174
494d3adb 175However, note that when upgrading between major versions (such as between
1761.4.x and 1.5.x), it is usually best to create a secondary preferences
177storage location and start with a fresh system for your users to configure.
178That said, many preferences are the same between versions and to date there
179are no known incompatibilities between 1.4.x preferences and 1.5.x preferences.
b8aaaa7b 180
494d3adb 181If you have your preferences stored inside your old SquirrelMail
182installation, we'd STRONGLY encourage you to re-read our installation
183information and consider moving them away from the web server's reach.
184If for some reason you need to continue to store your preferences inside
185the SquirrelMail installation, you can move the new data/ directory out
186of the way and copy the old preferences to the new installation:
8462c882 187
494d3adb 188 $ mv squirrelmail-1.4.17/data/ squirrelmail-1.4.17/data-new
189 $ cp -Rp squirrelmail-1.4.8/data/ squirrelmail-1.4.17/
8462c882 190
494d3adb 191If you are using Windows or otherwise cannot use the commands above, please
192make sure that you preserve the permissions and ownership of the data/
193directory as you move it, since SquirrelMail will not work unless the web
194server has write permission in the data directory (which, presumably, your
195old data directory has been set up with).
196
197PLEASE NOTE: If you are upgrading from versions lower than 1.0.5, you
198are STRONGLY encouraged NOT to migrate preferences, since there were
199important security upgrades in the preferences system starting with
200SquirrelMail version 1.0.5.
201
202
2034. Run the configuration utility
204=================================
205
c2428880 206Although not strictly necessary for minor upgrades, we STRONGLY
207recommend that you run config/conf.pl to see the new configuration
208options available with the new version, as well as to verify that
209all of your old options are set properly. In SquirrelMail versions
2101.5.2 and above, this also ensures that your plugins are properly
211registered with SquirrelMail.
494d3adb 212
213Always save your options, even if you haven't changed anything. This
214will ensure that any problems with your configuration that have been
215automatically detected and fixed are not lost.
216
217If you want to make sure that your configuration contains all themes
218included in new SquirrelMail package, go to theme options in
219configuration utility and run theme detection command.
220
221
2225. Visit src/configtest.php
223============================
224
225You should browse to http://example.com/squirrelmail/src/configtest.php
226(adjust the address to suit your system) and confirm that there are no
227configuration problems. Note that in versions 1.5.0 and up, you'll need
228to make sure $allow_remote_configtest is enabled in your configuration
229file to do so (or see "11. Tweaks" ==> "7. Allow remote configtest" in
230the configuration utility).
231
232
2336. Verify that the new installation works
234==========================================
235
236Log in and take a look around in your new installation and make sure
237everything is working as expected.
238
239
2407. Follow-up
241=============
242
243Once you've finished upgrading, you may want to keep an archived copy
244of your old installation just in case something goes wrong with the new
245one. You can simply move the whole directory somewhere else outside
246of your web server's document root or compress the directory into an
247archive file for storage elsewhere. Here's how to create a zip file
248of your old installation in a Linux-like environment:
249
250 $ cd /usr/share/
251 $ zip -r squirrelmail-1.4.8.zip squirrelmail-1.4.8
252
253Or to create a gzipped tar archive:
254
255 $ tar czvf squirrelmail-1.4.8.tar.gz squirrelmail-1.4.8
256
257Then make sure that you REMOVE the old directory so users can no longer
258access it - if you don't do this, you may be leaving yourself exposed
a95c75b3 259to known security exploits.
494d3adb 260
261
2628. How to point the web server to different SquirrelMail installations
263======================================================================
264
265In this guide, we assumed that your installation directories looked
266like "squirrelmail-1.4.17". Most of the time, you'll want to allow
267your users to type in "squirrelmail" (or just "webmail" or "mail")
268without needing to know the version number. Of course, you can simply
269change the name of the SquirrelMail installation directory:
270
271 $ cd /usr/share/
272 $ mv squirrelmail-1.4.8 mail
273
274... but there are several more graceful ways you can achieve this.
275In any Linux-like system, you can use symlinks to dynamically point
276"webmail" to any of your version-specific installations:
277
278 $ cd /usr/share/
279 $ ln -s squirrelmail-1.4.8 mail
280
281Note that symlinks can point anywhere you need them to, so the installation
282directory doesn't necessarily need to be in the same place the "mail" link
283is.
284
285You can also configure most any web server to point to your installation
286directory from any incoming address you desire. There are several
287redirection and address re-writing tools for most web servers, so this is
288just one example using Apache's Redirect directive:
289
290 Redirect permanent /squirrelmail-1.4.17 https://example.com/mail
291
292
2939. Version-specific upgrade issues
294==================================
295
c6211b0e 296Upgrading from the 1.4 release series to the 1.5 release series
297---------------------------------------------------------------
494d3adb 298
c6211b0e 299The plugin API changed substantially in version 1.5.2. At the least,
300you should NOT copy your old plugins when making this kind of upgrade.
494d3adb 301
302Upgrading from the 1.2 release series to the 1.4 release series
303---------------------------------------------------------------
304
305Several layout changes were made and there were other changes that require
306plugin updates. At the least, you should NOT copy your old plugins when
307making this kind of upgrade.
308
309Upgrading from any version older than 1.4.4 to version 1.4.4 or later
310---------------------------------------------------------------------
311
312Translations were removed from the main SquirrelMail package. Unless
313you copy the translations from your old installation, you will now need
314to visit the SquirrelMail download page and also get a copy of the our
315locales package.
f4057b81 316
494d3adb 317Downgrading from version 1.5.1 to any version older than 1.5.1
318--------------------------------------------------------------
4b45f6cb 319
494d3adb 320The "Index Order" options and SquirrelSpell user dictionaries will not be
321preserved if you use the same user preferences, although we discourage the
322use of the same preference sets between major release numbers (e.g., 1.4.x
323and 1.5.x).
f4057b81 324
c6211b0e 325Upgrading from any version older than 1.2.2 to version 1.2.2 or later
326---------------------------------------------------------------------
327
328The names used by some translations were changed starting in version 1.2.2.
329In most cases, you won't see any problems due to this change, however,
330the Norwegian Nynorsk (no_NO_ny) translation might need to be fixed. If
331you decide to retain the same preferences from your old installation, any
332users who have a "language" preference set to "no_NO_ny" will need to
333have it manually changed to "nn_NO".
334
335Upgrading from any version older than 1.0.5 to version 1.0.5 or later
336---------------------------------------------------------------------
337
338Some important security upgrades were made to the preferences system
339in version 1.0.5. It is NOT recommended that you retain user preferences
340when upgrading from versions older than 1.0.5.
341