Chapter 2. Applying Hotfix Patch to Fuse on Apache Karaf

2.1. Patching Features and Bundles

Patches are ZIP archives that contain the updated versions of files present in Fuse on Apache Karaf installation. These include:

  • Bundles: These are the most common and in the simplest case, hotfix patch may include single bundle.
  • Configuration files and scripts that are present respectively in $FUSE_HOME/etc and $FUSE_HOME/bin directories.
  • Libraries that are not ordinary bundles and reside in $FUSE_HOME/lib directory.
  • Feature definition changes: Normally Karaf features are included in descriptors available in the $FUSE_HOME/system directory, but hotfix patches do not change these files. Instead, hot fix patch may alter feature override file which is $FUSE_HOME/etc/org.apache.karaf.features.xml. This allows you to alter feature definitions in hotfix manner by upgrading given feature’s bundles or even make given feature use additional bundle.

Difference between Upgrading and Hotfix Patches

  • Hotfix Patch: A hotfix patch contains fixes for only one or more critical bugs. These are intended to be applied on top of your current Red Hat Fuse distribution. Its main purpose is to update some of the bundles and librabies in an existing distribution.
  • Upgrading: The Fuse on Apache Karaf upgrade mechanism enables you apply fixes to an Apache Karaf container without needing to reinstall an updated version of Fuse on Karaf. It also allows you to roll back the upgrade, if the upgrade causes problems with your deployed applications. The Fuse on Apache Karaf upgrade process updates any files, including bundle JARs, configuration files, and any static files.

For Fuse on Apache Karaf Standalone you can apply the patch using commands from the Karaf console’s patch shell. This approach is non-destructive and reversible. Following procedure can also be used for upgrading Red Hat Fuse on Apache Karaf. For more information of upgrading see Upgrading Fuse on Apache Karaf.

2.2. Applying a Hotfix Patch to Red Hat Fuse on Apache Karaf

You can use the hotfix mechanism to update the available feature definitions and bundles at the same time. The procedure to apply a hotfix patch to the Fuse on Apache Karaf installation is as follows.

Procedure

  1. Download the required patch from the Customer Portal.
  2. Make a full backup of your Fuse on Apache Karaf installation before upgrading.

  3. Open the terminal and start Fuse on Apache karaf server. 

    [user@FUSE_HOME/bin ~] $ ./fuse

  4. Add the patch to the container’s environment by entering the patch:add command. For example, to add the patch-xxx.zip patch file, enter: 

    karaf@root()> patch:add 'file:///Downloads/patch-xxx.zip'
[name]                 [installed] [rollup]   [description]
my-patch-x 	       false       false       my-patch-x

  5. Simulate installing the patch by entering 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 these changes.

  6. Enter patch:list command to view a list of added patches. In this list, the entries under the [name] heading are patch IDs. 

    patch:list
[name]                       [installed]   [description]
my-patch-x                   false

  7. Apply a patch to the container by entering the patch:install command and specifying the patch ID for the patch that you want to apply. 

    patch:install my-patch-x

2.3. Rolling back a Patch

You can rollback the installed hotfix patch and restore it to pre-patch behavior using the patch:rollback command, as follows:

Procedure

  1. Enter the patch:list command to obtain the patch ID of the most recently installed patch.

  2. To rollback the updated bundle enter the following command: 

    karaf@root()> patch:rollback my-patch-x
INFO : org.jboss.fuse.modules.patch.patch-management (2): Rolling back non-rollup patch "my-patch-x"
removing overriden feature: hawtio-rbac/2.0.0.fuse-000117
refreshing features
Enter feature:info command to view the information about the feature.
    karaf@root()> feature:info hawtio-rbac
Feature hawtio-rbac 2.0.0.fuse-000117
Details:
      Installs the hawtio RBAC enabler bundle(s)
Feature has no configuration
Feature has no configuration files
Feature has no dependencies.
Feature contains followed bundles:
      mvn:io.hawt/hawtio-osgi-jmx/2.0.0.fuse-000117
Feature has no conditionals.