Este conteúdo não está disponível no idioma selecionado.
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.NoteThe 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:
- 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.ImportantThe rollup number, N, of the downloaded patch management package must match the rollup number of the rollup patch you are about to install.NoteSurprisingly, 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.
- 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 thesystem/andpatches/subdirectories).NoteIt does not matter whether the container is running or not when you extract these files. - Start the container, if it is not already running.
- 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 ofpatch-featuresthat you have, because it might be different from1.2.0.redhat-621084. - 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 replace1.2.0.redhat-621xxxwith the actual build version of the patch commands you are installing (for example, the build versionxxxcan be taken from the last three digits of theTargetVersionin 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:
- Make a full backup of your JBoss A-MQ installation before attempting to apply the patch.
- (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”.
- (Rollup patch only) Remove the
lib/endorsed/org.apache.karaf.exception-2.4.0.redhat-621xxx.jarfile (where the build number,xxx, depends on the build being patched). - Before you proceed to install the patch, make sure to read the text of the
READMEfile that comes with the patch, as there might be additional manual steps required to install a particular patch. - 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. - Add the patch to the container's environment using the patch:add command. For example, to add the
patch.zippatch file:patch:add file://patch.zip
- 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.
- 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. - Apply the patch to the container using the patch:install command:
patch:install PatchID
NoteMake 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. - (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. - 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:
- Invoke the patch:list command to obtain the patch ID,
PatchID, of the most recently installed patch. - 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.
