This documentation is for WSO2 Carbon 4.4.3. View documentation for the latest release.
Page Comparison - WSO2 Patch Application Process (v.4 vs v.5) - Carbon 4.4.3 - WSO2 Documentation
Due to a known issue do not use JDK1.8.0_151 with WSO2 products. Use JDK 1.8.0_144 until JDK 1.8.0_162-ea is released.

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The patch application process described below guides you on how to manually apply security patches to Carbon 4.4.x-based products (if your product version is currently not supported by WUM). 

Table of Contents

Applying

...

patches to the product

A service pack is a collection of patches in a single pack. It contains two elements:

  • The lib directory: contains all the JARs relevant to the service pack.
  • The servicepack_patches.txt text file: contains the list of JARs in the service pack.

Follow the steps below to apply service packs to your product.

  1. Copy the service pack file to the <PRODUCT_HOME>/repository/components/servicepacks/ directory. For example, the image below shows how a new service pack named servicepack001 is added to this directory. 
    The servicepacks directory with the new servicepack001 subdirectory, which contains servicepack_patches.txt and the lib subdirectory with the patch JAR files.Image Removed
  2. Start your product. The following steps will be executed:
    1. Before applying any patches, the process first creates a backup folder named patch0000 inside the <PRODUCT_HOME>/repository/components/patches/ directory, which will contain the original content of the <PRODUCT_HOME>/repository/components/plugins/ directory. This step enables you to revert back to the previous state if something goes wrong during operations.

    2. The latest service pack in the <PRODUCT_HOME>/repository/components/servicepacks/ directory will be applied. That is, the patches in the service pack will be applied to the <PRODUCT_HOME>/repository/components/plugins/ directory.
    3. In addition to the service pack, if there are individual patches added to the <PRODUCT_HOME>/repository/components/patches/ directory, those will also be incrementally applied to the plugins directory. 

      Info

      The metadata file available in the service pack will maintain a list of the applied patches by service pack. Therefore, the metadata file will be compared against the <PRODUCT_HOME>/repository/components/patches/ directory, and only the patches that were not applied by the service pack will be incrementally applied to the plugins directory. 

Applying individual patches to the product

You can apply each patch individually to your system as explained below. Alternatively, you can apply patches through service packs as explained above.

...

You can apply patches to your product in two ways:

  • Apply each patch individually.
  • If you want to apply multiple patches, create a collective patch and apply it to the product. A collective patch is a single patch that includes all the JAR files from the individual patches that should be applied.

Follow the steps given below to apply an individual patch or a collective patch to the product:

  1. Copy the patches to the <PRODUCT_HOME>/repository/components/patches/ patches directory.
  2. Start the Carbon server. The patches will then be incrementally applied to the plugins directory.

    Note

    Before applying any patches, the process first creates a backup folder named patch0000 inside the <PRODUCT_HOME>/repository/components/patches/ directory, which will contain the original content of the <PRODUCT_HOME>/repository/components/plugins/ directory. This step enables you to revert back to the previous state if something goes wrong during operations.

Info

Prior to Carbon 4.2.0 version, users were expected to apply patches by starting the server with wso2server.sh -DapplyPatches. Now, you do not have to issue a special command to trigger the patch application process. It starts automatically if there are changes in either the  <PRODUCT_HOME>/repository/components/servicepacks/ directory or the <PRODUCT_HOME>/repository/components/patches/ directory. It verifies all the latest JARs in the servicepacks and patches directories against the JARs in the plugins directory by comparing the MD5s of JARs.

Verifying the patch application

...

  • All patch related logs are recorded in the <PRODUCT_HOME>/repository/logs/patches.log file.
  • The <PRODUCT_HOME>/repository/components/patches/.metadata/prePatchedJARs.txt meta file contains the list of patched JARs and the md5 values.
  • The patch directory information of all the applied patched will be in the <PRODUCT_HOME>/repository/components/default/configuration/prePatchedDir.txt file.

    Warning

    Do not change the data in the <PRODUCT_HOME>/repository/components/default/configuration/prePatchedDir.txt file. The patch application process gets the pre-patched list from this file and compares the list with the patches available in the patches directories. If you change the data in this file, you will get a startup error when applying patches.

Overview of the patch application process

The diagram below shows how the patch application process is implemented when you start the server.
Flow chart of patch application process. After server startup, if there are service packs or patch changes, they are applied. Next, MD5 verification is performed on the latest patched JARs against the JARs in plugin. Any warnings during this process are logged.  Image Removed