As the 7.0 version of Zarafa is coming closer and closer to the end of its support cycle we often receive the following question from customers and partners: “How do I update Zarafa to the most recent version?”
Keeping your Zarafa installation up to date is easy to achieve when you keep up with the regular updates. And an update from an old 7.0 release can also be done in a short time. The benefit of doing regular updates is that you get easy access to new features like an updated Zarafa WebApp or the first alpha release of our Exchange Webservices implementation called ZWS.
The following how-to will show you in detail how to perform the update from Zarafa 7.0.x to the most recent Zarafa 7.1 release. The update will be performed on a Ubuntu 12.04 system, but the general steps are the same for other distributions.
Preparation for the upgrade
Before we begin with the actual upgrade please make sure the following conditions are met:
- 1. You have an up to date, complete and restore-able backup of your current system. A full backup set is preferable, but for our case a backup of/etc/zarafa and a dump of your MySQL database will also be enough.
- 2. You have an active subscription and can convert your current serial to 7.1.
The full backup only serves as an additional layer of security in case anything goes wrong during the update. In general no problems or system delays are expected during the upgrade from 7.0 to 7.1.
Step 1 – Converting your serial to 7.1
The serial conversion can be done from inside the Zarafa portal. For this go to“Subscriptions” and choose “Convert subscription”. Here you can choose the desired serial from the dropdown box and then select 7.1 as the target version.
Upon clicking on convert you will see a popup explaining that a once converted serial cannot be converted back again. After accepting the portal will display the newly converted serial.
The serial will also be mailed to the email address associated to your account. Itcan later be viewed in the serial overview.
Step 2 – Download the packages
Now, go over to the “Download” section and download the latest 7.0 and 7.1 releases for your distribution
Extra tip 1: After selecting the distribution and architecture for your download a direct download link will be displayed. This link can be used to directly download the packages to your server (for example with wget)
Extra tip 2: To not receive a file that starts with “download_platform.php?…” you should enable the so called content disposition headers for wget. Example instructions can be found on the blog post: How to make wget honour Content-Disposition headers.
We now have all the requirements. And we can begin the update!
Doing the upgrade
The upgrade itself should be done when no one is working with the server (e.g. not during office hours), as you have to stop the zarafa-server process for several minutes which will lead to not responding mail clients.
Step 3 – Stop mail services
You should also stop new mails from coming in during the upgrade. This can easily be achieved by stopping all mail related services like your MTA (for example Postfix) or such services as fetchmail and getmail. Zarafa should be stopped as well to prevent your users from logging in. The fastest way to do this is to stop all services with a little “for loop” like “for PROC in /etc/init.d/zarafa-*; do $PROC stop; done”
Step 4 – Raise log level and enable safe mode
The Zarafa upgrade will now be done in two stages. In the first stage we are going to upgrade to the latest 7.0 release (the most recent version is 7.0.15 at time of writing). And after making sure that the upgrade went fine we will be going directly to the latest 7.1 release (currently 7.1.8).
As an additional precaution we will be enabling the so called “user_safe_mode”and raise the loglevel to 5 inside of the Zarafa server.cfg to see what’s going on during the upgrade.
Step 5 – Extract packages
Extract the most recent Zarafa 7.0 packages in a directory of choice:
Step 6 – Install packages
The easiest way to install the updated packages is to remove the packages you do not explicitly need (like zarafa-multiserver*.deb and later on pacemaker-zarafa*.deb). Finally, install all remaining packages with “dpkg -i *.deb”.
During the installation you will receive several questions if configuration files should be replace with newer versions:
You can always ignore these questions. We should keep the old configuration file as it is. At a later moment, we will update the file later when necessary. Congratulations: you have just updated your installation to the latest 7.0 version!
Step 7 – Check your upgrade
To check if the upgrade has been successful you should do a couple double checks:
- Check your server.log (for example with less or tail)
- List your users (zarafa-admin -l)
- Send an email (echo test | zarafa-dagent demo01)
- Login with WebApp and/or Outlook to check if your mails are still there.
Step 8 – Do the 7.1 upgrade
After you have made sure the 7.0 update was a success, stop the server again (for PROC in /etc/init.d/zarafa-*; do $PROC stop; done) and continue the upgrade to 7.1.
The first steps of the upgrade to 7.1 are similar to the steps in the upgrade to to 7.0.15. So, without further ado: Extract the downloaded package with tar, cd into the new folder, remove packages you do not need and then install the rest with “dpkg -i *.deb”.
During the execution of dpkg you ate again asked if you want to replace configuration files, once again you answer no and “keep your currently-installed version”. The first execution of dpkg will most propably fail, as packages such as zarafa-search need some new dependencies. But don’t worry and just go ahead by issuing “apt-get install -f” to get the missing dependencies.
You should now repeat the “dpkg -i *.deb” command to update the remaining packages.
Updating configuration files
With all the packages update to their latest versions, we now have to take a deeper look into the configuration files. We are going to update these files by removing and adding configuration options (you can find all of these listed in the Release Notes). Don’t worry about missing one of the new options; in case you forget to add one option its default value will be used. And this is fine for most Zarafa installations anyway.
Step 9 – Pinpoint new created files
To identify configuration files which need updating change into the /etc/zarafa directory.
Some of the files have the extension dpkg-dist. These have been created by dpkg, when you have answered not to update the existing files.
Step 10 – Remove old options and add new options in configuration files
I would like to point out a nice tool called confighelper which will help you to update your configuration files. You can get it in the Community Hub. Just download this script to your server, extract it with tar and then copy it over to /usr/local/bin for easy access.
Now for every file that has a second version if it ending in .dpkg-dist, use the following command (powered by confighelp.sh)confighelp.sh server.cfg server.cfg.dpkg-dist
In the first run the script will identify the options which have since then been removed from the configuration. For these you can simply open the corresponding file (server.cfg) and delete these. In the second run it will list options that are new and therefore potential candidates for inclusion. You can consult the man page of each configuration file to see which of the listed options you really have to include (for example man zarafa-server.cfg). In short; you only really have to remove the old zarafa-indexer related config options, everything else will work with default values.
Step 11 – Replace your serial
Please bear with me, we’re almost done. Now replace the serial inside of/etc/zarafa/license with your converted keys.
Step 12 – Test your new 7.1 installation
Don’t forget to do the same tests you previously did when upgrading to the latest 7.0 version (list users, send an email, login with a client).
Step 13 – The last mile
Everything is working okay? Nice job! These last steps will finish your upgrade:
- Reduce the log level inside server.cfg back to 2
- Issue a /etc/init.d/zarafa-server reload to re-read this change
- Start your mail transport again and you are good to go.
You can reply to this blog post in case you have any questions. You can also visit the community forums to ask your questions and get help from others. I only have one last thing to add: have fun upgrading!