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