In this article we will discuss WSO2 patches and the WSO2 Update Manager (WUM) tool. In addition, in this tutorial you will learn how to download and apply these patches, install this tool, and much more.
One of the main problems you may encounter when updating older WS02 versions is how to download and apply WSO2 patches, since you have to do it manually in older versions. However, more recent versions of WSO2 this is better managed.
This is a common problem since, even if you own a license for the product, few users know how to apply the patches. WSO2 provides you with the updated product (.zip), but it doesn’t allow deployment if you have already deployed the vanilla version (unpatched product). Therefore, it only allows you to apply the patches manually.
1. What is WSO2 Update Manager (WUM)?
WUM (WSO2 Update Manager) is a tool that WSO2 offers to download and apply its product patches, although it also has other functions.
In order to use this tool you need a WSO2 license. You won’t be able to use the tool otherwise.
This tool also helps you keep track of the product version you are downloading, as well as its patches.
2. WUM Installation
Installing the WSO2 Update Manager (WUM) tool is easy, you just have to follow these steps:
- First. Download the product from the official WSO2 website, https://wso2.com/wum/download:
wget http://product-dist.wso2.com/downloads/wum/3.0.5/wum-3.0.5-linux-x64.tar.gz
- Second. Unzip the TAR file on the preferred route.
tar -C /opt -xzf wum-3.0.5-linux-x64.tar.gz
- Third. Set the new route to $PATH in order to use the binary, otherwise you must use WUM’s full route.
export PATH=$PATH:/opt/wum/bin
Here you can download an alternative for Linux https://wso2.com/wum/download
3. WSO2 Update Manager (WUM) Commands
Once WUM is installed, the commands it has will be checked. Just by typing “wum” you will get a list of all the commands you can use.
root@c73956b85bda:/# wum WUM keeps WSO2 products up-to-date. Usage: wum [command] Available Commands: init Initialize WUM with your WSO2 credentials search Search products containing the specific keyword(s) add Add or download a product check-update Check new updates for products update Update products in your local repository diff Generate a diff comparing two updated product distributions list List products in your local repository describe Show details of products in your local repository delete Delete products in your local repository config Change WUM configuration version Display WUM version information Flags: -v, --verbose Enable verbose mode Use "wum [command] --help" for more information about a command.
3.1 Version
Start by checking the tool’s version. With this command you can test some of the tool specifications, such as the version of Go used, architecture and last update:
root@c73956b85bda:/# wum version wum version: 3.0.5 Release date: 2019-05-08 08:45:15 UTC OS\Arch: linux\amd64 Go version: go1.12.4
This is the only command you can use without a license. If you use another command, this will be the result:
root@c73956b85bda:/# wum list wum: you haven't initialized WUM with your WSO2 credentials Run 'wum init' to continue
3.2. init
To start using WSO2 Update Manager (WUM), you must register using the init option, followed by your email and password. If you wish, you can just put your email and it will ask for your password. This way you won’t leave your password visible:
root@c73956b85bda:/# wum init You need a WSO2 subscription to start using WUM. Don't have one yet? Sign up for a free-trial subscription at https://wso2.com/subscription/free-trial Please enter your WSO2 credentials to continue Email: correo@gmail.com Password for correo@gmail.com': Authenticating... *** New version of WUM is now available. Please visit http://wso2.com/update to download. *** Done! Setting default channel full... -- Welcome to WUM 3.0.5 -- * Please contact WSO2 for further information at https://wso2.com/contact What's next? Have a look at the following list of WUM commands: Add WSO2 products to your product repository wum search Search WSO2 products wum add Add or download WSO2 products Update WSO2 products available in your product repository wum check-update Check for new updates wum update Update your WSO2 products wum diff Create a diff between two updated distributions Manage WSO2 products available in your product repository wum list List WSO2 products wum describe Show details of WSO2 products wum delete Delete WSO2 products
WUM always gives us information about which command you can use.
3.3. Search
This command shows the latest versions of the products you can download:
root@c73956b85bda:/# wum search Connecting to WSO2 Update Server... Available latest products Product Description wso2am-3.0.0 API Manager wso2am-analytics-3.0.0 API Manager Analytics wso2am-micro-gw-linux-3.0.2 API Microgateway Linux wso2am-micro-gw-macos-3.0.2 API Microgateway MacOS wso2am-micro-gw-toolkit-2.5.0 API Microgateway Toolkit wso2am-micro-gw-windows-3.0.2 API Microgateway Windows wso2cep-4.2.0 Complex Event Processor wso2das-3.2.0 Data Analytics Server wso2dss-3.5.1 Data Services Server wso2ei-6.6.0 Enterprise Integrator wso2emm-2.2.0 Enterprise Mobility Manager wso2esb-5.0.0 Enterprise Service Bus wso2esb-analytics-5.0.0 Enterprise Service Bus Analytics wso2greg-5.4.0 Governance Registry wso2iot-3.3.1 IoT Server wso2iot-3.3.0 IoT Server wso2is-5.9.0 Identity Server wso2is-analytics-5.8.0 Identity Server Analytics wso2is-km-5.9.0 IS as Key Manager wso2mb-3.2.0 Message Broker wso2mi-1.0.0 Micro Integrator wso2si-1.0.0 Streaming Integrator wso2si-tooling-1.0.0 Streaming Integrator Tooling wso2sp-4.4.0 Stream Processor Subscribed channels None
It also shows the different channels, referring to the products with installed patches:
Do you want to see all available latest channels? [y/N] y All available latest channels Product Channel wso2am-3.0.0 full,security wso2am-analytics-3.0.0 full,security wso2am-micro-gw-linux-3.0.2 full wso2am-micro-gw-macos-3.0.2 full wso2am-micro-gw-toolkit-2.5.0 full,security wso2am-micro-gw-windows-3.0.2 full wso2cep-4.2.0 full wso2das-3.2.0 full wso2dss-3.5.1 full wso2ei-6.6.0 full,security wso2emm-2.2.0 full wso2esb-5.0.0 full wso2esb-analytics-5.0.0 full wso2greg-5.4.0 full wso2iot-3.3.0 full wso2iot-3.3.1 full wso2is-5.9.0 full,security wso2is-analytics-5.8.0 full,security wso2is-km-5.9.0 full,security wso2mb-3.2.0 full wso2mi-1.0.0 security wso2mi-monitoring-dashboard-1.1.0 full wso2mi-monitoring-dashboard-1.1.1 full,security wso2si-1.0.0 full,security wso2si-tooling-1.0.0 full,security wso2sp-4.4.0 full,security
Lastly, note that the tool itself indicates the next step you should take:
What's next? run "wum add <product-name>-<product-version>" to download a product run "wum update <product-name>-<product-version> <channel>" to update a product
You can also filter by products:
root@c73956b85bda:/# wum search wso2ei Connecting to WSO2 Update Server... Available latest products Product Description wso2ei-6.6.0 Enterprise Integrator Subscribed channels None
3.4. Add
This command enables you to add the product you want:
root@c73956b85bda:/# wum add wso2ei-6.6.0 Connecting to WSO2 Update Server... The product, "wso2ei-6.6.0.zip", will be downloaded. After this operation, 511.6MB of additional disk space will be used. Do you want to continue? [Y/n] y Downloading product wso2ei-6.6.0.zip... [511MB/511MB] (100%) - 0kB/s 0s remaining Download complete Successfully added to following location: /home/root/.wum3/products/wso2ei/6.6.0/wso2ei-6.6.0.zip
After downloading WSO2 it will ask what your next step is:
What's next? run "wum check-update <product-name>-<product-version> <channel>" to check for updates run "wum update <product-name>-<product-version> <channel>" to install latest updates
3.5 Check-update
This command allows you to check for patches for your current version, whether you have the original product or if you’ve already downloaded some patches:
root@c73956b85bda:/# wum check-update wso2ei-6.6.0 Connecting to WSO2 Update Server... Using default channel full... Checking updates for wso2ei-6.6.0 via full channel... There are 9 updates available for the product 'wso2ei-6.6.0'. [WARNING] There are 6 critical security updates for the product 'wso2ei-6.6.0'. WSO2 strongly recommends to apply these updates in production as soon as possible.
As you can see, WSO2 is telling you that there are 9 updates available. WSO2 also indicates the next steps:
run "wum update <product-name>-<product-version>" to update the product in the default channel
run "wum update <product-name>-<product-version> <channel>" to update the product in the specified channel
3.6. Update
This command enables you to download the patches you want, be it for a product or a full version (products with patches). When a full version has patches available, it is outdated.
root@c73956b85bda:/# wum update wso2ei-6.6.0 Connecting to WSO2 Update Server... Using default channel full... Updating wso2ei-6.6.0 via full channel... There are 9 updates available for the product 'wso2ei-6.6.0'. Downloading updates... [9/9] - 0s remaining Installing updates... Preparing summary... Building updated product... Update summary: Update count: 9 [WARNING] There are 6 critical security updates for the product 'wso2ei-6.6.0'. WSO2 strongly recommends to apply these updates in production as soon as possible. Updated product: /home/root/.wum3/products/wso2ei/6.6.0/full/wso2ei-6.6.0+1584025788848.full.zip * More information about updates are available inside the above product archive. Update summary (pdf): (/home/root/.wum3/products/wso2ei/6.6.0/full/wso2ei-6.6.0+1584025788848.full.zip)/updates/summary/update-summary-wso2ei-6.6.0+1584025788848.full.pdf * The above update summary has also been emailed to [correo@gmail.com].
Once the update is done, you will get an email with a pdf specifying the changes made since the last update. If it is the first time, you will get all the changes that were made. Note that some manual changes need to made for some configuration files.
WSO2 indicates the next step:
What's next? run "wum list [product-pattern]" to list products in your local repository run "wum describe [product-pattern]" to get more details of products run "wum diff <updated-distribution-1> <updated-distribution-2>" to create a diff between the given updated product distributions
3.7. List
This command shows the products you have downloaded, for both the vanilla (unpatched product) and the full versions:
root@c73956b85bda:/# wum list Product Updated Filename Channel wso2ei-6.6.0 xxxx-xx-xxxxx:xx:xx+xx:xx wso2ei-6.6.0+xxxxxxxxxxxxxxx.full.zip full wso2ei-6.6.0 - wso2ei-6.6.0.zip -
As you can see, it shows 2 products: the original version (wso2ei-6.6.0, -, wso2ei-6.6.0.zip, -) and the one you downloaded (wso2ei-6.6.0, xxxx-xx-xxxxx:xx:xx+xx:xx, wso2ei-6.6.0+xxxxxxxxxxxxxxx.full.zip, ful ).
Lastly, WSO2 indicates which command to use next:
What's next? run "wum describe [product-pattern]" to get more details of products
3.8. Describe
This command describes the product:
root@c73956b85bda:/# wum describe wso2ei-6.6.0 Filename: wso2ei-6.6.0+xxxxxxxxxx.full.zip Product Name: wso2ei Product Version: 6.6.0 Channel Name: full Kernel Version: 4.5.3 Last Updated Time: xxxx-xx-xxxxx:xx:xx+xx:xx Product File Path: /home/root/.wum3/products/wso2ei/6.6.0/full/wso2ei-6.6.0+xxxxxxxx.full.zip No Of Times Updated: 1 Installed Updates: 9 Update History: Date Installed Updates Username xxxx-xx-xxxxx:xx:xx+xx:xx 9 correo@gmail.com Filename: wso2ei-6.6.0.zip Product Name: wso2ei Product Version: 6.6.0 Channel Name: - Kernel Version: 4.5.3 Last Updated Time: - Product File Path: /home/root/.wum3/products/wso2ei/6.6.0/wso2ei-6.6.0.zip
You can ascertain details such as: the route where the product is located, the kernel version, features of the product version, name and available updates.
3.9. Diff
This command allows you to distinguish between different versions of the same product:
root@c73956b85bda:/# wum diff wso2ei-6.6.0+xxxxxxxxx.full.zip wso2ei-6.6.0.zip Connecting to WSO2 Update Server... Creating a diff between the product distributions, 'wso2ei-6.6.0' and 'wso2ei-6.6.0+xxxxxxxxx.full'... Preparing summary... Diff summary: Update count: 9 [WARNING] There are 6 critical security updates for the product 'wso2ei-6.6.0'. WSO2 strongly recommends to apply these updates in production as soon as possible. Diff archive: /home/root/.wum3/wso2ei-6.6.0-diff-0-xxxxxxxxx.full.zip * More information about updates are available inside the above diff archive. Diff summary (pdf): (/home/root/.wum3/wso2ei-6.6.0-diff-0-xxxxxxxxx.full.zip)/updates/summary/diff-summary-wso2ei-6.6.0-full+xxxxxxxxx.pdf * The above diff summary has also been emailed to [correo@gmail.com].
It shows you the difference between the wso2ei-6.6.0.zip and the full version you previously downloaded. These differences are reflected in a pdf file as indicated below. You will also receive an email.
3.10. Config
With this command you can change WSO2’s work route. The route of the user who made the “init” is used by default. That is, if you use root, the default route will be “/home/root/.w3m”. However, you can change this if you wish:
root@c73956b85bda:/home/root# mkdir wso2_folder root@c73956b85bda:/home/root# wum config local.product.repo /home/root/wso2_folder/ New product repository is /home/root/wso2_folder
Now, add a product to verify this:
root@7862c719402a:/home/root# wum add wso2ei-6.6.0 Connecting to WSO2 Update Server... The product, "wso2ei-6.6.0.zip", will be downloaded. After this operation, 511.6MB of additional disk space will be used. Do you want to continue? [Y/n] y Downloading product wso2ei-6.6.0.zip... [511MB/511MB] (100%) - 0kB/s 0s remaining Download complete Successfully added to following location: /home/root/wso2_folder/wso2ei/6.6.0/wso2ei-6.6.0.zip What's next? run "wum check-update <product-name>-<product-version> <channel>" to check for updates run "wum update <product-name>-<product-version> <channel>" to install latest updates
Check that it was downloaded:
root@7862c719402a:/home/root# tree wso2_folder/
wso2_folder/
`-- wso2ei
`-- 6.6.0
`-- wso2ei-6.6.0.zip
2 directories, 1 file
4. Folder and File Structure of the WUM Tool
One you have registered, added and updated some products, the local WSO2 Update Manager (WUM) repository, local.product.repo (as the path was changed from “.w3m” to “wso2_folder” when the config command was redefined), begins to increase in volume.
Here, you will find an explanation for each file and folder type..
When you launch the tool for the first time, a hidden folder called wum3 will be created in the home directory of the user. If you changed the configuration and redefined the route, you should check the redefined route in the local directory local.product.repo:
root@c73956b85bda:~# ls -la | grep wum3 drwxr-xr-x 5 root root 4096 Mar 11 21:14 .wum3
In this directory you will find:
- The config.yml. file.
- The products/ directory.
- The updates/ directory.
4.1. config.yml file
The config.yml file is a configuration file that contains information about your account, user, authentication token, product version, product you are downloading and kernel version, among other things.
root@c73956b85bda:~/.wum3# cat config.yaml
username: correo@gmail.com
local.product.repo: /root/.wum3/products
local.update.repo: /root/.wum3/updates
defaultchannel: full
repositories:
wso2:
enabled: true
name: WSO2 Update Repository
url: https://api.updates.wso2.com
tokenurl: https://api.updates.wso2.com/token
appkey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
refreshtoken: xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
accesstoken: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
products: {}
In the “product” directory you will find information about your downloaded products:
Products: {}
wso2ei-6.4.0:
name: wso2ei
version: 6.4.0
productdir: /home/root/.wum3/products/wso2ei/6.4.0
kernel-version: 4.4.36
channel: full
4.2. Products Directory
In the products/ directory you will find the products you have downloaded. It is broken down into 3 levels:
- In the first level you will find the product you downloaded (wso2ei).
- The second level contains the multiple versions of the product you downloaded (6.4.0).
- The third level contains the zip product (wso2ei-6.4.0.zip) and a final directory called “full” which contains the zip version of the product with the applied patches. There will be both compressed full products and product updates.
├── products │ └── wso2ei │ └── 6.4.0 │ ├── full │ │ ├── wso2ei-6.4.0+XXXXXXXXXXXXX.full.zip │ │ ├── wso2ei-6.4.0+XXXXXXXXXXXXX.full.zip │ │ ├── wso2ei-6.4.0+XXXXXXXXXXXXX.full.zip │ │ ├── wso2ei-6.4.0+XXXXXXXXXXXXX.full.zip │ │ ├── wso2ei-6.4.0+XXXXXXXXXXXXX.full.zip │ └── wso2ei-6.4.0.zip
4.3 Updates Directory
The updates/ directory stores each update in zip format. It also has different levels, based on the product’s kernel. Unlike the “products” folder, this directory provides direct access to the patches.
For example, in the first update, there may be a total of 7 WSO2-CARBON-UPDATE-4.4.0-****.zip in the “update” folder, but in “products” there will only be one zip. In “products” you have the original zip with all the patches available at the time you update, while in “updates” you have the patches, so you would have to apply them manually. The result is the same.
└── updates
└── wilkes
└── 4.4.0
├── WSO2-CARBON-UPDATE-4.4.0-XXXX.zip
├── WSO2-CARBON-UPDATE-4.4.0-XXXX.zip
├── WSO2-CARBON-UPDATE-4.4.0-XXXX.zip
├── WSO2-CARBON-UPDATE-4.4.0-XXXX.zip
├── WSO2-CARBON-UPDATE-4.4.0-XXXX.zip
In this case, when downloading WSO2ei-6.4.0, a specific version of the platform, 4.4.0, is used, so the release will be wilkes. WSO2 chooses the name. For more information about the different releases, check this link: LINK
Therefore, if you download another product, like WSO2ei-6.6.0, the structure will be:
├── minsky
│ └── 4.5.0
│ ├── WSO2-CARBON-UPDATE-4.5.0-XXXX.zip
│ ├── WSO2-CARBON-UPDATE-4.5.0-XXXX.zip
│ ├── WSO2-CARBON-UPDATE-4.5.0-XXXX.zip
│ ├── WSO2-CARBON-UPDATE-4.5.0-XXXX.zip
│ └── WSO2-CARBON-UPDATE-4.5.0-XXXX.zip
└── wilkes
└── 4.4.0
├── WSO2-CARBON-UPDATE-4.4.0-XXXX.zip
├── WSO2-CARBON-UPDATE-4.4.0-XXXX.zip
├── WSO2-CARBON-UPDATE-4.4.0-XXXX.zip
└── WSO2-CARBON-UPDATE-4.4.0-XXXX.zip
You will have different releases depending on the product.
5. Manual Installation of the WSO2 Patches
To apply the patches manually, i.e apply a series of WSO2-CARBON-UPDATE-4.4.0-****.zip, you have to follow a logical order from lowest to highest. This is becausesometimes, the binaries are modified in a zip, but there may be a newer patch with a higher value, which may have also been modified and has greater preference.
How do you know which patch has a higher value? In this case, WSO2-CARBON-UPDATE-4.4.0-0123.zip has a lower value than WSO2-CARBON-UPDATE-4.4.0-2560.zip, so if the 2560 modified a binary that was also touched by 0123, the 2560 must prevail over 0123.
Once you have understood this, you can move on to see what’s contained in these zip files. The structure is usually like this:
WSO2-CARBON-UPDATE-4.4.0-XXXX ├── carbon.home │ └── bin │ ├── update_darwin │ └── update_linux ├── LICENSE.txt ├── NOT_A_CONTRIBUTION.txt ├── update-descriptor3.yaml └── update-descriptor.yaml WSO2-CARBON-UPDATE-4.5.0-XXXX ├── carbon.home │ └── wso2 │ └── components │ └── plugins │ └── org.wso2.carbon.endpoint.ui_4.7.30.jar ├── LICENSE.txt ├── NOT_A_CONTRIBUTION.txt └── update-descriptor3.yaml
- The “carbon.home” folder contains the patches that are included.
- The “yaml” file or files describe what is added, modified and deleted., It is usually named update-descriptor3.yaml, but it could also be update-descriptor.yml.
- The remaining files contain information about licenses, etc.
How do I apply patches? The file update-descriptor3.yaml (might have another name) has information about the patches contained in the “carbon.home” directory and the ones that are appropriate for you. We will use WSO2ei-6.4.0 as an example:
First. As you can see, there is a short description of the patch and its version, kernel version, etc..
update_number: XXXX platform_version: 4.4.0 platform_name: wilkes md5sum: xxxxxxxxxxxxxxxxxxxxxx description: | The WSO2 in-place updates tool allows you to update your currently used product by fetching updates from the server and merging all configurations and files. The tool also gives backup and restore capability. instructions: | N/A bug_fixes: https://github.com/wso2/carbon-kernel/issues/xxxx: Add In-place updates client
Second. In compatible_products you can see which patches should be applied, as well as the patches that will be modified or deleted.
As you can see, it is displayed as a list. You have to search for your product (product_name), in this case wso2ei. Then, the full version of your product (product_version), in this case 6.4.0.full. You will have to apply the patches. There are 3:
- added_files: files that will be added.
- modified_files: files that will be updated.
- delete_files: files that will be deleted.
compatible_products: - product_name: wso2am product_version: 2.6.0.full added_files: - bin/update_darwin - bin/update_linux removed_files: [] modified_files: [] - product_name: wso2is-km product_version: 5.7.0.full added_files: - bin/update_darwin - bin/update_linux removed_files: [] modified_files: [] - product_name: wso2ei product_version: 6.4.0.full added_files: - bin/update_darwin - bin/update_linux removed_files: [] modified_files: []
The patches will indicate if you have to add, modify or delete them.
Third. This part is the same as the second part, but the name will be partially_applicable_products, instead of “compatible_products”. The function is the same, but it is for a specific product and its version.
To apply the patches you have to copy-paste each file into the appropriate directory, as its route indicates. Starting from the carbon.home directory, where we have installed the carbon product.
The only difference between compatible_products and partially_applicable_products, is:
- compatible_products: patches that are generally applied o WSO2 products, be it EI, IS or AM, among others. As mentioned above, they are applied only if they are included in the list. These patches are applicable to all products.
- partially_applicable_products: patches that are applied to specific products, i.e. different versions of the same product, e.g. from WSO2 Enterprise Integrator, we can distinguish 6.4.0, 6.5.0, 6.6.0, etc.
We continue with the yaml files we can find, in this case update-descriptor.yml
update_number: XXXX platform_version: 4.4.0 platform_name: wilkes applies_to: wso2am-2.6.0 bug_fixes: https://github.com/wso2/carbon-kernel/issues/xxxx: Add In-place updates client description: The WSO2 in-place updates tool allows you to update your currently used product by fetching updates from the server and merging all configurations and files. The tool also gives backup and restore capability. file_changes: added_files: - bin/update_darwin - bin/update_linux removed_files: [] modified_files: []
As you can see, the way to apply the changes is very similar to that of update-descriptor3.yml, but it only indicates that it is applicable to a specific product (wso2am-2.6.0). The way in which they are applied comes at the end:
added_files: - bin/update_darwin - bin/update_linux removed_files: [] modified_files: []
It indicates which files you should add, but not which files will be deleted and/or updated.
Conclusion
With this summary of commands provided by WSO2 Update Manager (WUM), you will be able to easily deal with WSO2 patches
Even if you have the necessary knowledge to apply the WSO2 patches, you have to be incredibly careful when applying them, because a badly installed patch can lead to the WSO2 service becoming corrupted. This is because some patches depend on other patches.
This tool will allow you to control your environment by applying patches that work properly.
