WSO2 Update Tool | How to apply patches and updates with the 2.0 model

This article will cover how to apply patches and how to make a updates with the 2.0 model (Wso2 Update tool)

We will use the following index:

1. Concepts

• Update: a collection of bug fixes, new features, security fixes, and upgrades. Updates are distributed through levels. When an update is applied to a product, the product level is increased by one.
• Hotfix: These are immediate fixes provided for bugs reported by customers. A hotfix is delivered in a zip file. It is recommended for use on critical issues that have not been fixed in previous updates.

Note: the commands change according to the operating system used:

GNU/Linux:
{WSO2_HOME}/bin/wso2update_linux
MacOS:
{WSO2_HOME}/bin/wso2update_darwin
Windows:
{WSO2_HOME}/bin/wso2update_windows.exe

2. Requirements

The WSO2 Update Tool requires internet access for the following addresses from devices on which WSO2 products are installed:

3. Preparation

In this case, Identity Server 5.10.0 will be updated on a Debian GNU/Linux 10.0 system and with JDK version 1.8.051. Before starting the update process, it is advisable to validate the current version of the WSO2 update tool using the following command which will show the installed version:

{WSO2_HOME}/bin/wso2update_linux version

Log in to confirm whether or not there is a newer version of the tool, and if so, update it:

{WSO2_HOME}/bin/wso2update_linux -u user@user.com -p password123

Note: the parameters -p and -u are optional

The latest version of the tool can be downloaded manually via the following URL:  https://product-dist.wso2.com/downloads/update-tool/release/update.zip

4. Switching to the 2.0 model

In order to perform an update using the new WSO2 tool, it is necessary to perform the model change, which involves updating the WSO2 product to the latest available timestamp.

Confirm that updates are available for our WSO2 product.

{WSO2_HOME}/bin/wso2update_linux check

Note: This action will delete the wum folder and the files located in it: {WSO2_HOME}/updates/wum

Coming from the previous model (WUM), the product level will be -1 (wso2is-5.10.0.0). The latest available level, so far 49 will also be displayed along with the number of available updates (193) and the number of critical updates (8).

The next step is to update the WSO2 product to the latest available timestamp using the wum tool.

Upon completion of the update, the product is updated to the latest available level using the WSO2 Update Tool.

{WSO2_HOME}/bin/wso2update_linux -b /datos/backup/ -u user@user.com

Note: Not updating the model may result in errors when searching for or performing updates.

5. Updating products

Get to know the current level of the product

{WSO2_HOME}/bin/wso2update_linux check

Validate if updates are available

{WSO2_HOME}/bin/wso2update_linux check

Upgrade to a specific level (2):

{WSO2_HOME}/bin/wso2update_linux -l 2 -b /datos/backup/

6. Updating products (WUM diff)

In the newly updated model, there is a version similar to the wum diff that enables you to create an update and update it later:

Create an update that starts at level 1 and ends at level 2.

-e, –end-level string    End update level

-s, –start-level string Start update level

{WSO2_HOME}/bin/wso2update_linux create-update -s 1 -e 2

Apply a previously created update

{WSO2_HOME}/bin/wso2update_linux apply-update <ruta_update>

7. Reversing an update

Inside the /data/backup/backup folder (specified with the -b parameter), the folders with the created backups will be generated:

Reverse an update and restore the last backup generated

{WSO2_HOME}/bin/wso2update_linux --revert

8. HOTFIX

A hotfix is an update provided by WSO2 to fix critical incidents reported by customers via a ticket, the WSO2 team will provide a .zip file.

To apply the hotfix, the following command, indicating the path to the zip file, must be executed.

{WSO2_HOME}/bin/wso2update_linux apply-hotfix <HF_zip>

Once the hotfix is released at a certain level it is recommended that the hotfix be uninstalled and the product be upgraded to the indicated level:

{WSO2_HOME}/bin/wso2update_linux --revert-hotfix

9. Portal Updates

When an update is installed on a WSO2 product, it will be registered on the WSO2 update portal:  https://updates-info.wso2.com

In the Browse Account menu, the installed products are displayed, with the last installed update and the recommended update:

In the Update Levels menu, it is possible to search for available updates by product and level.

Selecting Download generates a report in PDF format with the selected updates, instructions, modified files, deleted files, etc.

Selecting an update displays information about the resolved issue.

10. Resolving conflicts for WSO2 Update tool

If there are any files such as css, js, jsp, etc. that have been modified, there will be a conflict when applying an update, so a merge will be required.

Note: WSO2 does NOT recommend modifying the original jar and car files.

WSO2 recommends keeping the same indentation (spaces/tabs) in jag, js or json files, otherwise conflicts may occur.

In the following example, the wso2-default.min.css and pom.properties files were modified within the authentication endpoint. When performing an update, conflicts occur with the files

In case of conflicts when trying to update a product, 3 versions of the conflicting file will be created, e.g.:

• wso2-default.min.css: current file with modifications installed in WSO2 product
• wso2-default.min.css.new: new version of the file with the changes downloaded in the last level
• wso2-default.min.css.original: original version of the file without modifications and the latest available updates

A new wso2-default.min.css.final file should be created, it is recommended that it contain the new changes from the .new file, which can be obtained via a diff.

diff wso2-default.min.css.new wso2-default.min.css.original

When it is complete, run the update again with the continue parameter.

This will delete the .new, .original and .final files by replacing the wso2-default.min.css file with wso2-default.min.css.final.

11. Docker

The WSO2 Update Tool enables you to create a docker image with the updates and modifications displayed in a simpler way by using the following command:

{WSO2_HOME}/bin/wso2update_linux  create-docker

12. Common errors WSO2 Update tool

WSO2 Update Tool will replace the modified templates (*.j2), removing any added changes. When applying the update, there will be no conflict with the files, so no errors or warnings about deletion of the changes will be displayed.

If WSO2 Update Tool cannot find a file that has been removed from the product (e.g. wso2-default.min.css), it will not allow the update to go ahead. This will result in a conflict while the file exists.

WSO2 Update Tool has no support for arm architectures.

If you want to know how Chakray can help you, then contact us!