On occasion, this depending on many issues like newness of the product as well as vulnerabilities in the WSO2 product, it is necessary to patch WSO2 products. If a new patch is available it will be available on the WSO2 website in case of security patches. When you have a support contract a patch can also be made available for you taking care of an issue that occurred in your organization.
In both cases you need to apply the patches to the WSO2 product in order to update the product.
How do you patch?
Patching is quite simple. Shutdown the WSO2 product, drop the downloaded and unpacked patch (its a zipfile, use for instance WINRAR or 7-ZIP to view the contents) into the [WSO2_PRODUCT_HOME]/repository/components/patches directory and thewso2carbon-version.txt into [WSO2_PRODUCT_HOME]/bin. At startup the patches will be detected and applied to the WSO2 product.
Apart from the actual patch directory and the wso2carbon-version.txt file the patch also contains a README and License file.
The README describes the content of the patch and any specific comments to its installation. (e.g. dependencies with other patches). The license file describes the license under which the patch is released.
What happens behind the scenes?
When the patching process starts new patches are detected and deployed to the plugins directory. This process also happens when you start the WSO2 product for the first time, you get a message “Patch changes detected”.
During this initial product start the plugins directory is copied into patch0000 as backup after which the patches are applied into the plugins directory.
The patching itself is done by a Java class: org.wso2.carbon.server.util.PatchUtilswhich is part of the org.wso2.carbon.server-4.2.0 jar (4.2.0 is the current version of carbon).
Removing patches
Installed patches can also be removed according to WSO2. However this requires knowledge of the contents of the patches. There can be instances where patches depend on other patches. We will get to that later in this article.
There is also a patches.log file in the [CARBON_HOME]/repository/logs directory that indicates the patches that have been applied when starting the WSO2 product.
This is the content (abridged) of the patches.log file after starting WSO2 product for the first time:
[2015-09-12 17:39:52,163] INFO {org.wso2.carbon.server.util.PatchUtils} – Checking for patch changes …
[2015-09-12 17:39:52,163] INFO {org.wso2.carbon.server.util.PatchUtils} – New patch available – patch0001
…
[2015-09-12 17:39:52,163] INFO {org.wso2.carbon.server.extensions.PatchInstaller} - Patch changes detected[2015-09-12 17:39:56,283] INFO {org.wso2.carbon.server.util.PatchUtils} - Backed up plugins to patch0000[2015-09-12 17:39:56,283] INFO {org.wso2.carbon.server.util.PatchUtils} - Applying patches ...[2015-09-12 17:39:56,283] INFO {org.wso2.carbon.server.util.PatchUtils} - Applying - patch0001[2015-09-12 17:39:56,373] INFO {org.wso2.carbon.server.util.PatchUtils} - Patched …[2015-09-12 17:39:56,733] INFO {org.wso2.carbon.server.util.PatchUtils} - Patched wss4j_1.5.11.wso2v6.jar(MD5:6af11b00c0d4c20c933454cdc4346522)[2015-09-12 17:39:56,733] INFO {org.wso2.carbon.server.util.PatchUtils} - Applying - patch0002[2015-09-12 17:39:56,733] INFO {org.wso2.carbon.server.util.PatchUtils} - Patched axis2-transport-jms_1.1.0.wso2v9.jar(MD5:e278aa1875a65d68622c576a5d0b27b4)
Let suppose, as a test, we remove the patch0002 directory from[WSO2_PRODUCT_HOME]/repository/components/patches. After deleting this directory (and restarting the WSO2 product) the bundle backup directory is restored and the patches that remain are reinstalled. The patches.log shows the actions that have been taken.
[2015-09-12 17:43:17,429] INFO {org.wso2.carbon.server.extensions.PatchInstaller} - Patch changes detected
[2015-09-12 17:43:17,429] INFO {org.wso2.carbon.server.util.PatchUtils} - Applying patches
...
[2015-09-12 17:43:17,429] INFO {org.wso2.carbon.server.util.PatchUtils} - restoring bundle backup directory
[2015-09-12 17:43:21,189] INFO {org.wso2.carbon.server.util.PatchUtils} - Applying - patch0001
[2015-09-12 17:43:21,259] INFO {org.wso2.carbon.server.util.PatchUtils} - Patched axiom_1.2.11.wso2v4.jar(MD5:d0b5b01650ca4faae96a54bbc733441f)
…
[2015-09-12 17:43:21,659] INFO {org.wso2.carbon.server.util.PatchUtils} - Applying - patch0003
[2015-09-12 17:43:21,659] INFO {org.wso2.carbon.server.util.PatchUtils} - Patched jdbc-pool_7.0.34.wso2v1.jar(MD5:d097808a51bd2e71217e3ac7f08b5f8e)
[…
[2015-09-12 17:43:22,459] INFO {org.wso2.carbon.server.util.PatchUtils} - Patch verification started
[2015-09-12 17:43:22,859] INFO {org.wso2.carbon.server.util.PatchUtils} - Patch verification successfully completed without encountering any issues
The challenges lie in determining the dependencies between patches. In some case patch X relies on patch Y. So you cannot remove Y since X depends on it.
A patch can also involve some manual activity like where you need to manually replace the certain files . In such cases, all steps are described in the README.txt included in the patch zip file. If you want to rollback the patch you need to revert the manual changes (i.e. restoring the file or files from saved copies during the patch process) as well.
Be careful
Patching WSO2 remains something that needs to be done with care. For one you need to shut down the WSO2 product and apply the patches. The content of the patches (as described in the readme file) needs to be studied carefully and after that the patches can be deployed.
This of course after making backups, testing it and so on. Testing also means testing the functionality of the WSO2 product against your deployment.
Patching mostly happens after instructions from WSO2. They know you installed patches and therefor can make the decision of how and when to apply or remove which patch. Security patches can be downloaded from the WSO2 website for each product.
WSO2Easy blogs are a collaboration between several consultants. In this case thanks go out to Rob Blaauboer, Joris Jansen and Ronald Everts for their contribution.
