WSO2's new product update model

Image Source:

If you have gone through my previous blog post on WSO2 update channels or have used any WSO2 product at past, you surely have used WUM or the in-place update tool at least once for updating your WSO2 product. Since the release of wum in 2016, it became the most popular way of retrieving an up to date WSO2 product distribution among many users all around the globe, as it is quicker and efficient than the legacy approach of applying patches one by one.

⚠️ Please note that although WSO2 provides security fixes as patches along with security advisory announcements, WSO2 strongly recommends updating your product distributions to the latest version available with either wum or the in-place update tool as updates provide bug-fixes, improvements and new features to your product distribution, in addition to the security updates.

With the feed-backs we received from our user base all over the world for the past few years, we led our efforts in finding ways to optimizing the current WSO2 product update process. As a result we came up with a new update model which is more efficient and more quicker than previous models ( both wum and in-place) and we calls this new model Updates 2.0. So lets dig further on what’s new in Updates 2.0 and how it differs from previous update tools like wum or the in-place update tool.

  • Three new platform specific update tools (namely wso2update_linux, wso2update_darwin and wso2update_windows.exe)
  • Introduction of update levels instead of timestamps for updated product distributions (ex: wso2am- instead of wso2am-3.2.0+1602172186640).
  • Version bumping of components (Ex: org.wso2.carbon.cluster.mgt.core_4.5.1.jar -> org.wso2.carbon.cluster.mgt.core_4.5.1.1.jar)
  • Updates and hot-fixes.
  • Consumes very low bandwidth when compared with both wum and in-place update tools.
  • More convenient way of viewing details of updates applied to your product distribution via the new WSO2 Updates Portal.
  • Bi-weekly update releases which will help you to schedule update cycles more easily in your environment. ( do not worry, for critical security issues we will release new update levels ASAP and notify all users on them 🔔 )

Updates are the proactive fixes (containing bug fixes, feature additions and improvements) provided by WSO2 for product distributions. At present both wum or the in-place update tool uses these updates for updating your product distributions. So what are hot-fixes?

Hot-fixes are user specific, temporary fixes provided to a user for resolving a current production issue at hand. These fixes will be provided in the form zip files via the user specific support-jira account when the user reported a critical bug in their production environment. A hot-fix provided above is meant only to be used, until the proper fix is being shipped via an update in future. Once the fix is released as an update, the user should revert the previously applied hot-fix and update his/her product distribution to the latest update level available as soon as possible

The three platform specific update tools will be available inside the <PRODUCT_HOME>/bin directory of your product distribution as follows,

  • wso2update_linux
  • wso2update_darwin
  • wso2update_windows.exe

These update tools will be readily available in the latest products that you download from and for other products (previous products), the new update tools will get added to the product distribution once you update your product distribution to the latest timestamp( either using wum or the in-place update tool)

It is pretty simple, all you have to do is run the tool without any argument as follows to update your product distribution to the latest update level available,

During the execution, it will prompt you for your WSO2 account as shown above, you could enter a valid account if any or you could just press Enter to continue with a free trial subscription. In either case your product distribution will gets updated to its latest update level 😃. In above my product distribution got updated from wso2am- to the wso2am- which is the latest update level of wso2am-3.1.0.

As you could observe in above, during the update process a backup of my previous distribution is taken which I can safely use to restore my product distribution (to the state before running the update tool) if required 👍.

⚠️ Note: If you have used in-place update tool at past for updating your product distribution, the new update tool will prompt you for confirmation on the migration to the new update model as shown above. Please note that if you grant the migration, the old update tool in-place will be deleted permanently and you no longer will be able to receive updates to your product distribution from the old update model again.

Sometimes when running the new update tool for the first time for migrating to the new update model, you might end up with the message as follows,

The reason for the above is that WSO2 delivers updates on bi-weekly basic in the new updates model, hence if you have recently obtained an updated product distribution either from WUM/in-place, those corresponding updates will be available in the next release cycle of the new update model. So the tool will notify this to you and will automatically exits execution.

Now lets see common use cases of the update tool :

If you like, you can update your product distribution to a desired update level instead of to the latest update level available, by running the following command.

You can also provide the desire update level as a single digit (without the product base version) as follows,

./wso2update_linux --level 1

If your workflow hit with a bug after the update or you might want to stick to the previous product version for what ever reason, you can simply run the following command which will restore your product distribution to the state just before running the update tool.

Sometimes when updating your product distribution you might end up with a conflict message like follows,

this happens when files been modified from WSO2 updates, are also modified by yourself. To fix the issue you have to manually review and resolve the conflict files listed and rename the resolved files with .final extension. Once the resolved files are renamed with .final you can resume the update process by running the update tool with --continue flag as follows.

For more details conflict resolving please go through the conflict resolving documentation

Sub commands of the update tool

Beside above the update tool also has some additional sub commands that will be useful in the long run.

As you could observe above, running the current-state sub-command will provide you details of your current product distribution. This will show on what update level your product is at and the list of hot-fixes applied if any. Providing the details output from this sub command during opening up a support ticket at Jira is very useful, as the output contains all the initial details which will be helpful in analyzing your issue.


The check sub-command can be used to check for the availability of new update levels for your product distribution. This will also list the number of security fixes been provided on the available new update level.

The help sub-command can be used to get the help of any command. There is also a — help argument that can be used with any sub-command to get the help of that sub-command. For example

  • To get the help of check sub-command you can run
./wso2update_line check --help
  • To get the help of create-docker sub-command you can run
./wso2update_linux create-docker --help

Please refer the official documentation and webinar for more details on the Updates 2.0.

Cheers ❗❗❗



Senior Software Engineer, @WSO2

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store