SupportConsoleDevelopersStart a trialContact

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

Before upgrading JBoss A-MQ with a rollup patch, you must patch the patch mechanism to a higher level. Since the original GA version of JBoss A-MQ 6.2 was released, significant improvements have been made to the patch mechanism. 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.2.0 Software Downloads page, select a package named Red Hat JBoss A-MQ 6.2.1 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.
    Note
    Surprisingly, the 6.2.1 patch management packages are made available from the 6.2.0 Software Downloads page. This is because the 6.2.1 patch management packages can also be used when upgrading from version 6.2.0.
  2. Install the patch management package, patch-management-for-amq-620-TargetVersion.zip, on top of your 6.2.1 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-621084
    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-621084/xml/features
JBossFuse:karaf@root> features:removeurl mvn:io.fabric8.patch/patch-features/1.2.0.redhat-621084/xml/features
    Check the version of patch-features that you have, because it might be different from 1.2.0.redhat-621084.
  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-621xxx/xml/features
    Where you must replace 1.2.0.redhat-621xxx 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-621xxx
[ 266] [Active     ] [            ] [       ] [    2] mvn:io.fabric8.patch/patch-management/1.2.0.redhat-621xxx
[ 267] [Active     ] [            ] [       ] [   80] mvn:io.fabric8.patch/patch-commands/1.2.0.redhat-621xxx

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-621xxx.jar file (where the build number, xxx, depends on the build being patched).
  4. 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 using the patch:add command. For example, to add the patch.zip patch file: 
    patch:add file://patch.zip
  7. Simulate installing the patch using the patch:simulate command.
    This will generate 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 all added patches. From this list, you can get the ID, PatchID, of the patch you want to install.
  9. Apply the patch to the container using the patch:install command: 
    patch:install PatchID
    Note
    Make sure that the container has fully started before you run patch:install.
    In some cases the container will need to restart to apply the patch (for example, if static files are patched). In these cases, the container restarts automatically.
  10. (Windows only) On Windows operating systems, the container cannot restart automatically. You typically see an error message like the following: 
    Rollup patch jboss-fuse-full-6.2.1.redhat-xxx installed. Restarting Karaf..
JBossA-MQ:karaf@root>
Restarting JVM...
Updating libs...
        1 dir(s) moved.
Karaf can't startup, make sure the log file can be accessed and written by the user starting Karaf : java.io.IOException: Unable to delete file: ...
    In this case, you just need to restart the container manually.
  11. 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 621084
[   6] [Active     ] [            ] [       ] [   10] org.apache.felix.configadmin    (1.2.0.redhat-621084)
    After applying a rollup patch, you will 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.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.