| 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. |
| 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 | |
| 296 | Upgrading from the 1.4 release series to the 1.5 release series |
| 297 | --------------------------------------------------------------- |
| 298 | |
| 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. |
| 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. |
| 316 | |
| 317 | Downgrading from version 1.5.1 to any version older than 1.5.1 |
| 318 | -------------------------------------------------------------- |
| 319 | |
| 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). |
| 324 | |
| 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 | |