Chapter 6. Applying Patches

Abstract

Red Hat Fuse supports incremental patching. FuseSource will supply you with easy to install patches that only make targeted changes to a deployed container.

6.1. Patching Overview

Patching enables you apply fixes to a Karaf container without needing to reinstall an updated version of Fuse on Karaf. It also allows you to back out the patch, if it causes problems with your deployed applications.

Patches are ZIP files that contain the artifacts needed to update a targeted set of bundles in a container. The artifacts are typically one or more bundles. They can, however, include configuration files and feature descriptors.

You get a patch file in one of the following ways:

  • Customer Support sends you a patch.
  • Customer Support sends you a link to download a patch.
  • Download a patch directly from the Red Hat customer portal.

The process of applying a patch to a container depends on how the container is deployed:

  • Standalone (standard process) — using commands from the Karaf console’s patch shell. This approach is non-destructive and reversible.

6.2. Finding the Right Patches to Apply

Abstract

This section explains how to find the patches for a specific version of Fuse on the Red Hat Customer Portal and how to figure out which patches to apply, and in what order.

Locate the patches on the customer portal

If you have a subscription for Fuse, you can download the latest patches directly from the Red Hat Customer Portal. Locate the patches as follows:

  1. Login to the Red Hat Customer Portal using your customer account. This account must be associated with an appropriate Red Hat software subscription, otherwise you will not be able to see the patch downloads for Fuse.
  2. Navigate to the customer portal Software Downloads page.
  3. In the Product dropdown menu, select Red Hat Fuse and then select the version, 7.1, from the Version dropdown menu. A table of downloads now appears, which has three tabs: Releases, Patches, and Security Advisories.
  4. Click the Releases tab to view the GA product releases.
  5. Click the Patches tab to view the rollup patches and the regular incremental patches (with no security-related fixes).
  6. Click the Security Advisories tab to view the incremental patches with security-related fixes.
Note

To see the complete set of patches, you must look under the Releases tab, the Patches tab and the Security Advisories tab.

Types of patch

The following types of patch can be made available for download:

  • Rollup patches
  • Incremental patches

Rollup patches

A rollup patch is a cumulative patch that incorporates all of the fixes from the preceding patches. Moreover, each rollup patch is regression tested and establishes a new baseline for the application of future patches.

In Fuse, a rollup patch file is dual-purpose, as follows:

  • Each rollup patch file is a complete new build of the official target distribution. This means you can unzip the rollup patch file to obtain a completely new installation of Fuse, just as if it was a fresh download of the product (which, in fact, it is). See Section 6.3, “Installing a Rollup Patch as a New Installation”.
  • You can also treat the rollup patch as a regular patch, using it to upgrade an existing installation. That is, you can provide the rollup patch file as an argument to the standalone patch console commands (for example, patch:add and patch:install) or the Fabric patch console command, patch:fabric-install.

Incremental patches

Incremental patches are patches released either directly after GA or after a rollup patch, and they are intended to be applied on top of the corresponding build of Fuse. The main purpose of an incremental patch is to update some of the bundles in an existing distribution.

Which patches are needed to update the GA product to the latest patch level?

To figure out which patches are needed to update the GA product to the latest patch level, you need to pay attention to the type of patches that have been released so far:

  1. If the only patches released so far are patches with GA baseline (Patch 1, Patch 2, and so on), apply the latest of these patches directly to the GA product.
  2. If a rollup patch has been released and no patches have been released after the latest rollup patch, simply apply the latest rollup patch to the GA product.

  3. If the latest patch is a patch with a rollup baseline, you must apply two patches to the GA product, as follows:

    1. Apply the latest rollup patch, and then
    2. Apply the latest patch with a rollup baseline.

Which patches to apply, if you only want to install regression-tested patches?

If you prefer to install only patches that have been regression tested, install the latest rollup patch.

6.3. Installing a Rollup Patch as a New Installation

A rollup patch is a new build

In Fuse, a rollup patch file is a complete new build of the official target distribution. In other words, it is just like the original GA distribution, except that it includes later build artifacts.

Installing the new build

To install a new build, corresponding to a rollup patch level, perform the following steps:

  1. Identify which rollup patch you need to install and download it from the Customer Portal. For more details, see Section 6.2, “Finding the Right Patches to Apply”.
  2. Unzip the rollup patch file to a convenient location, just as you would with a regular GA distribution. This is your new installation of Fuse.

Comparison with patch process

Compared with the conventional patch process, installing a new build has the following advantages and limitations:

  • This approach is only for creating a completely new installation of Fuse. If your existing installation already has a lot of custom configuration, this might not be the most convenient approach to use.
  • The new build includes only the artifacts and configuration for the new patch level.

6.4. Patching a Standalone Container

Abstract

You apply patches to a standalone container using the command console’s patch shell. You can apply and roll back patches as needed.

Overview

When patching a standalone container, you can apply either an incremental patch or a rollup patch. There are very significant differences between the two kinds of patch and the way they are applied. Although the same commands are used in both cases, the internal processes are different (the patch commands auto-detect the patch type).

Incremental patch

An incremental patch is used mainly to update the bundle JARs in the container. This type of patch is suitable for delivering hot fixes to the Fuse installation, but it has its limitations. An incremental patch:

  • Updates bundle JARs.
  • Patches only the current container instance (under the data/ directory). Hence, patches are not preserved after deleting a container instance.
  • Updates any feature dependencies installed in the current container instance, but does not update the feature files themselves.
  • Might update some configuration files, but is not suitable for updating most configuration files.
  • Supports patch rollback.

After applying an incremental patch to a standalone container, meta-data about the patch is written to the etc/startup.properties and etc/overrides.properties files. With these files, the Karaf installation is able to persist the patch even after deleting the root container instance (that is, after removing the root container’s data/ directory).

Note

Removing the data/cache directory uninstalls any bundles, features, or feature repositories that were installed into the container using Karaf console commands. You can remove the data/cache directory only after you stop the container. However, any patches that have been applied will remain installed, as long as the etc/startup.properties and etc/overrides.properties files are preserved.

Rollup patch

A rollup patch can make updates to any installation files including bundle JARs and static files (including, for example, configuration files under the etc/ directory). A rollup patch:

  • Updates any files, including bundle JARs, configuration files, and any static files.
  • Patches both the current container instance (and its runtime storage under the data/ directory) and the underlying installation. Hence, patches are preserved after deleting a container instance.
  • Updates all of the files related to Karaf features, including the features repository files and the features themselves. Hence, any features installed after the rollup patch will reference the correct patched dependencies.
  • If necessary, updates configuration files (for example, files under etc/), automatically merging any configuration changes you have made with the configuration changes made by the patch. If merge conflicts occur, see the patch log for details of how they are handled.
  • Most of the merge conflicts are resolved automatically. For example, the patch mechanism detects conflicts at property level for the property files. It detects whether it was a user or patch that changed any property. The change is preserved, if only one side changed the property.

  • Tracks all of the changes made to the installation (including to static files), so that it is possible to roll back the patch.

    Note

    The rollup patching mechanism uses an internal git repository (located under patches/.management/history) to track the changes made.

Patching the patch mechanism

(Recommended, if applicable) If there is no patch management package corresponding to the rollup patch you are about to install, then you can skip this procedure and install the rollup patch directly.

From time to time, important changes and improvements are made to the patch mechanism. In order to pick up these improvements, we recommend that you patch the patch mechanism to a higher level before upgrading Fuse with a rollup patch. If you were to upgrade straight to the latest rollup patch version of Fuse, the improved patch mechanism would become available after you completed the upgrade. But at that stage, it would be too late to benefit from the improvements in the patch mechanism.

To circumvent this bootstrap problem, the improved patch mechanism is made available as a separate download, so that you can patch the patch mechanism itself, before you upgrade to the new patch level.

Note

The fuse-patch-management-<version>.zip archive is used to quickly patch the patching mechanism.

To patch the patch mechanism, proceed as follows:

  1. Download the appropriate patch management package. From the download page, select a package named Red Hat Fuse 7.x.x Rollup N on Karaf Update Installer, where N is the number of the particular rollup patch you are about to install.

  2. Install the patch management package on top of your existing installation. Use an archive utility to extract the contents on top of the existing Karaf container installation (installing files under the system/ subdirectory).

    Note

    It does not matter whether the container is running or not when you extract these files.

  3. Start the container, if it is not already running.
  4. Run the patch:update command. There is no need to restart the container. 
karaf@root()> la -l|grep patch

233 │ Active   │  80 │ 7.0.0.fuse-000191-redhat-1    │ mvn:org.jboss.fuse.modules.patch/patch-commands/7.0.0.fuse-000191-redhat-1
234 │ Active   │  35 │ 7.0.0.fuse-000191-redhat-1    │ mvn:org.jboss.fuse.modules.patch/patch-core/7.0.0.fuse-000191-redhat-1
235 │ Active   │  35 │ 7.0.0.fuse-000191-redhat-1    │ mvn:org.jboss.fuse.modules.patch/patch-core-api/7.0.0.fuse-000191-redhat-1
236 │ Active   │   2 │ 7.0.0.fuse-000191-redhat-1    │ mvn:org.jboss.fuse.modules.patch/patch-management/7.0.0.fuse-000191-redhat-1

karaf@root()> patch:update --simulation

Current patch mechanism version: 7.0.0.fuse-000191-redhat-1
New patch mechanism version detected: 7.0.1.fuse-000011-redhat-3

karaf@root()> patch:update

Current patch mechanism version: 7.0.0.fuse-000191-redhat-1
New patch mechanism version detected: 7.0.1.fuse-000011-redhat-3
Uninstalling patch features in version 7.0.0.fuse-000191-redhat-1
Installing patch features in version 7.0.1.fuse-000011-redhat-3

karaf@root()> la -l|grep patch

237 │ Active   │  80 │ 7.0.1.fuse-000011-redhat-3    │ mvn:org.jboss.fuse.modules.patch/patch-commands/7.0.1.fuse-000011-redhat-3
238 │ Active   │  35 │ 7.0.1.fuse-000011-redhat-3    │ mvn:org.jboss.fuse.modules.patch/patch-core/7.0.1.fuse-000011-redhat-3
239 │ Active   │  35 │ 7.0.1.fuse-000011-redhat-3    │ mvn:org.jboss.fuse.modules.patch/patch-core-api/7.0.1.fuse-000011-redhat-3
240 │ Active   │   2 │ 7.0.1.fuse-000011-redhat-3    │ mvn:org.jboss.fuse.modules.patch/patch-management/7.0.1.fuse-000011-redhat-3

karaf@root()> patch:update

Current patch mechanism version: 7.0.1.fuse-000011-redhat-3
No newer version of patch bundles detected

Applying a patch

To apply a patch to a standalone container:

  1. Make a full backup of your Fuse installation before attempting to apply the patch.
  2. (Rollup patch only) Before applying the rollup patch to your container, you must patch the patch mechanism, as described in the section called “Patching the patch mechanism”.
  3. (Incremental patch only) Before you proceed to install the patch, make sure to read the text of the README file that comes with the patch, as there might be additional manual steps required to install a particular patch.
  4. Start the container, if it is not already running. If the container is running in the background (or remotely), connect to the container using the SSH console client, bin/client.

  5. Add the patch to the container’s environment by invoking the patch:add command. For example, to add the patch.zip patch file: 

    patch:add file://patch.zip

  6. Simulate installing the patch by invoking the patch:simulate command.

    This generates a log of the changes that will be made to the container when the patch is installed, but will not make any actual changes to the container. Review the simulation log to understand the changes that will be made to the container.

  7. Invoke the patch:list command to display a list of added patches. In this list, the entries under the [name] heading are patch IDs. For example: 

    karaf@root()> patch:list

[name]  [installed] [rollup] [description]

fuse-karaf-7.1.0.fuse-710018-redhat-00001 false  true  fuse-karaf-7.1.0.fuse-710018-redhat-00001

    Ensure that the container has fully started before you try to perform the next step. In some cases, the container must restart before you can apply a patch, for example, if static files are patched. In these cases, the container restarts automatically.

  8. Apply a patch to the container by invoking the patch:install command and specifying the patch ID for the patch that you want to apply. For example: 

    karaf@root()> patch:install fuse-karaf-7.1.0.fuse-710018-redhat-00001

  9. Validate the patch, by searching for one of the patched artifacts. For example, if you had just upgraded Fuse 7.1.0 to the patch with build number N, you could search for bundles with this build number, as follows: 

    karaf@root()> la -l|grep 710018

  2 │ Active   │   2 │ 7.1.0.fuse-710018        │ mvn:org.jboss.fuse.modules.patch/patch-management/7.1.0.fuse-710018

 22 │ Active   │  80 │ 7.1.0.fuse-710018        │ mvn:org.jboss.fuse.modules/fuse-pax-transx-tm-narayana/7.1.0.fuse-710018

 24 │ Active   │  80 │ 2.0.0.fuse-710018        │ mvn:io.hawt/hawtio-log/2.0.0.fuse-710018

 25 │ Active   │  80 │ 2.0.0.fuse-710018        │ mvn:io.hawt/hawtio-log-osgi/2.0.0.fuse-710018

 26 │ Active   │  80 │ 2.0.0.fuse-710018        │ mvn:io.hawt/hawtio-osgi-jmx/2.0.0.fuse-710018

After applying a rollup patch, you also see the new version and build number in the Welcome banner when you restart the container.

Rolling back a patch

Occasionally a patch will not work or will introduce new issues to a container. In these cases, you can easily back the patch out of the system and restore it to pre-patch behaviour using the patch:rollback command, as follows:

  1. Invoke the patch:list command to obtain the patch ID, PatchID, of the most recently installed patch.

  2. Invoke the patch:rollback command, as follows: 

    patch:rollback PatchID

    In some cases the container will need to restart to roll back the patch. In these cases, the container restarts automatically. Due to the highly dynamic nature of the OSGi runtime, during the restart you might see some occasional errors related to incompatible classes. These are related to OSGi services that have just started or stopped. These errors can be safely ignored.