494d3adb |
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. |
47f9c368 |
6 | |
f4057b81 |
7 | |
494d3adb |
8 | 0. Check requirements |
9 | ===================== |
f4057b81 |
10 | |
494d3adb |
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. |
8462c882 |
17 | |
494d3adb |
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. |
2b996daf |
21 | |
8462c882 |
22 | |
494d3adb |
23 | 1. What to do with your old installation |
24 | ========================================= |
f4057b81 |
25 | |
494d3adb |
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"). |
f4057b81 |
31 | |
494d3adb |
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). |
f4057b81 |
35 | |
2b996daf |
36 | |
494d3adb |
37 | 2. Unpack new SquirrelMail |
38 | =========================== |
f4057b81 |
39 | |
494d3adb |
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 | ============================================== |
f4057b81 |
58 | |
8462c882 |
59 | The 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 | |
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. |
f4057b81 |
95 | |
494d3adb |
96 | B. Plugins |
97 | ----------- |
b8aaaa7b |
98 | |
494d3adb |
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!). |
b8aaaa7b |
104 | |
494d3adb |
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. |
8462c882 |
111 | |
494d3adb |
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): |
8462c882 |
115 | |
494d3adb |
116 | $ cp -Rp squirrelmail-1.4.8/plugins/email_footer squirrelmail-1.4.17/plugins/ |
f4057b81 |
117 | |
494d3adb |
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: |
8462c882 |
121 | |
494d3adb |
122 | $ cp -p squirrelmail-1.4.8/config/config_email_footer.php squirrelmail-1.4.17/config/ |
8462c882 |
123 | |
494d3adb |
124 | C. Skins |
125 | --------- |
b8aaaa7b |
126 | |
494d3adb |
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 | ---------- |
8462c882 |
158 | |
159 | If you've created or modified themes, you should copy just those to the new |
494d3adb |
160 | SquirrelMail themes directory: |
8462c882 |
161 | |
494d3adb |
162 | $ cp -pi squirrelmail-1.4.8/themes/* squirrelmail-1.4.17/themes/ |
3fe751d7 |
163 | |
8462c882 |
164 | |
494d3adb |
165 | F. Preferences |
166 | --------------- |
f4057b81 |
167 | |
494d3adb |
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. |
f4057b81 |
174 | |
494d3adb |
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. |
b8aaaa7b |
180 | |
494d3adb |
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: |
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 |
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 | |
c2428880 |
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. |
494d3adb |
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 |
a95c75b3 |
259 | to known security exploits. |
494d3adb |
260 | |
261 | |
262 | 8. How to point the web server to different SquirrelMail installations |
263 | ====================================================================== |
264 | |
265 | In this guide, we assumed that your installation directories looked |
266 | like "squirrelmail-1.4.17". Most of the time, you'll want to allow |
267 | your users to type in "squirrelmail" (or just "webmail" or "mail") |
268 | without needing to know the version number. Of course, you can simply |
269 | change 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. |
275 | In 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 | |
281 | Note that symlinks can point anywhere you need them to, so the installation |
282 | directory doesn't necessarily need to be in the same place the "mail" link |
283 | is. |
284 | |
285 | You can also configure most any web server to point to your installation |
286 | directory from any incoming address you desire. There are several |
287 | redirection and address re-writing tools for most web servers, so this is |
288 | just one example using Apache's Redirect directive: |
289 | |
290 | Redirect permanent /squirrelmail-1.4.17 https://example.com/mail |
291 | |
292 | |
293 | 9. Version-specific upgrade issues |
294 | ================================== |
295 | |
c6211b0e |
296 | Upgrading from the 1.4 release series to the 1.5 release series |
297 | --------------------------------------------------------------- |
494d3adb |
298 | |
c6211b0e |
299 | The plugin API changed substantially in version 1.5.2. At the least, |
300 | you should NOT copy your old plugins when making this kind of upgrade. |
494d3adb |
301 | |
302 | Upgrading from the 1.2 release series to the 1.4 release series |
303 | --------------------------------------------------------------- |
304 | |
305 | Several layout changes were made and there were other changes that require |
306 | plugin updates. At the least, you should NOT copy your old plugins when |
307 | making this kind of upgrade. |
308 | |
309 | Upgrading from any version older than 1.4.4 to version 1.4.4 or later |
310 | --------------------------------------------------------------------- |
311 | |
312 | Translations were removed from the main SquirrelMail package. Unless |
313 | you copy the translations from your old installation, you will now need |
314 | to visit the SquirrelMail download page and also get a copy of the our |
315 | locales package. |
f4057b81 |
316 | |
494d3adb |
317 | Downgrading from version 1.5.1 to any version older than 1.5.1 |
318 | -------------------------------------------------------------- |
4b45f6cb |
319 | |
494d3adb |
320 | The "Index Order" options and SquirrelSpell user dictionaries will not be |
321 | preserved if you use the same user preferences, although we discourage the |
322 | use of the same preference sets between major release numbers (e.g., 1.4.x |
323 | and 1.5.x). |
f4057b81 |
324 | |
c6211b0e |
325 | Upgrading from any version older than 1.2.2 to version 1.2.2 or later |
326 | --------------------------------------------------------------------- |
327 | |
328 | The names used by some translations were changed starting in version 1.2.2. |
329 | In most cases, you won't see any problems due to this change, however, |
330 | the Norwegian Nynorsk (no_NO_ny) translation might need to be fixed. If |
331 | you decide to retain the same preferences from your old installation, any |
332 | users who have a "language" preference set to "no_NO_ny" will need to |
333 | have it manually changed to "nn_NO". |
334 | |
335 | Upgrading from any version older than 1.0.5 to version 1.0.5 or later |
336 | --------------------------------------------------------------------- |
337 | |
338 | Some important security upgrades were made to the preferences system |
339 | in version 1.0.5. It is NOT recommended that you retain user preferences |
340 | when upgrading from versions older than 1.0.5. |
341 | |