16.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).
Important
The instructions in this section apply only to JBoss A-MQ versions 6.2.1 and later, which support the new patching mechanism.

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 JBoss A-MQ 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 the patch, and creating a new fabric using fabric:create, the new Fabric reverts to the unpatched configuration.
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. 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 (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.
  • 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.
  • After applying the patch, and creating a new fabric using fabric:create, the new Fabric is created with the patched configuration.

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 JBoss A-MQ with a rollup patch. If you were to upgrade straight to the latest rollup patch version of JBoss A-MQ, 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. To patch the patch mechanism, proceed as follows:
  1. Download the appropriate patch management package. From the JBoss A-MQ 6.3.0 Software Downloads page, select a package named Red Hat JBoss A-MQ 6.3.0 Rollup N on Karaf Update Installer, where N is the number of the particular rollup patch you are about to install.
    Important
    The rollup number, N, of the downloaded patch management package must match the rollup number of the rollup patch you are about to install. For some rollup patches, there is no corresponding patch management package, in which case you can skip directly to the instructions for installing the rollup patch.
  2. Install the patch management package, patch-management-for-amq-630-TargetVersion.zip, on top of your 6.3.0 installation. Use an archive utility to extract the contents on top of the existing Karaf container installation (installing files under the system/ and patches/ subdirectories).
    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. Uninstall the existing patch commands from the container as follows. Remove the patch features as follows: 
    JBossFuse:karaf@root> features:uninstall patch patch-core
    But this is not sufficient to remove all of the patch bundles. Check for any remaining patch bundles as follows: 
    JBossFuse:karaf@root> list -t 0 -l | grep patch

[   1] [Active     ] [            ] [       ] [    2] mvn:io.fabric8.patch/patch-management/1.2.0.redhat-630187
    You can remove this system bundle, as follows: 
    JBossFuse:karaf@root> uninstall 1
You are about to access system bundle 1.  Do you wish to continue (yes/no): yes
JBossFuse:karaf@root> list -t 0 -l | grep patch
    Finally, you should remove the features URL for the old patch mechanism version, as follows: 
    JBossFuse:karaf@root> features:listurl | grep patch
  true    mvn:io.fabric8.patch/patch-features/1.2.0.redhat-630187/xml/features
JBossFuse:karaf@root> features:removeurl mvn:io.fabric8.patch/patch-features/1.2.0.redhat-630187/xml/features
    Check the version of patch-features that you have, because it might be different from 1.2.0.redhat-630187.
  5. Install the new patch commands as follows. Add the features URL for the new patch commands, as follows: 
    JBossFuse:karaf@root> features:addurl mvn:io.fabric8.patch/patch-features/1.2.0.redhat-630xxx/xml/features
    Where you must replace 1.2.0.redhat-630xxx with the actual build version of the patch commands you are installing (for example, the build version xxx can be taken from the last three digits of the TargetVersion in the downloaded patch management package file name).
    Install the new patch features, as follows: 
    JBossFuse:karaf@root> features:install patch-core patch
    Check that the requisite patch bundles are now installed: 
    JBossFuse:karaf@root> list -t 0 -l | grep patch
[ 265] [Active     ] [            ] [       ] [   80] mvn:io.fabric8.patch/patch-core/1.2.0.redhat-630xxx
[ 266] [Active     ] [            ] [       ] [    2] mvn:io.fabric8.patch/patch-management/1.2.0.redhat-630xxx
[ 267] [Active     ] [            ] [       ] [   80] mvn:io.fabric8.patch/patch-commands/1.2.0.redhat-630xxx
  6. Restart the container (the patch:add command and the other patch commands will not be available in the console shell until you perform a restart).

Applying a patch

To apply a patch to a standalone container:
  1. Make a full backup of your JBoss A-MQ 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. (Rollup patch only) Remove the lib/endorsed/org.apache.karaf.exception-2.4.0.redhat-630xxx.jar file (where the build number, xxx, depends on the build being patched).
  4. (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.
  5. 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.
  6. 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
  7. 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.
  8. 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: 
     patch:list
[name]                       [installed]   [description]
jboss-a-mq-6.3.0.redhat-329  false
    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.
  9. 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: 
    patch:install jboss-a-mq-6.3.0.redhat-329
  10. Validate the patch, by searching for one of the patched artifacts. For example, if you had just upgraded JBoss A-MQ 6.2.1 to the patch with build number 621423, you could search for bundles with this build number, as follows: 
    JBoss A-MQ:karaf@root> osgi:list -s -t 0 | grep -i 630187
[   6] [Active     ] [            ] [       ] [   10] org.apache.felix.configadmin    (1.2.0.redhat-630187)
    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.

Adding features to an incrementally patched container

Since JBoss A-MQ 6.1, it is possible to add Karaf features to an already patched standalone container without performing any special steps.