19.4. Patching a Standalone Container
- 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.
etc/overrides.propertiesfiles. 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/cachedirectory 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/overrides.propertiesfiles are preserved.
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
- Download the appropriate patch management package. From the JBoss Fuse 6.3.0 Software Downloads page, select a package named Red Hat JBoss Fuse 6.3.0 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. 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.
- Install the patch management package,
patch-management-for-fuse-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
patches/subdirectories).ImportantEnsure the credentials you are using to unzip the file are the same credentials used to install Fuse; otherwise, an error may occur since Fuse will not have access to the patched file.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-coreBut 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-630xxxYou 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 patchFinally, 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-630xxx/xml/features JBossFuse:karaf@root> features:removeurl mvn:io.fabric8.patch/patch-features/1.2.0.redhat-630xxx/xml/featuresCheck the version of
patch-featuresthat you have, because it might be different from
- 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/featuresWhere you must replace
1.2.0.redhat-630xxxwith the actual build version of the patch commands you are installing (for example, the build version
xxxcan be taken from the last three digits of the
TargetVersionin the downloaded patch management package file name).Install the new patch features, as follows:
JBossFuse:karaf@root> features:install patch-core patchCheck 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
- Restart the container (the
patch:addcommand and the other patch commands will not be available in the console shell until you perform a restart).
Applying a patch
- Make a full backup of your JBoss Fuse 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-630xxx.jarfile (where the build number,
xxx, depends on the build being patched).
- (Incremental patch only) 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,
- Add the patch to the container's environment by invoking the patch:add command. For example, to add the
- 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.
- 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 falseEnsure 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.
- 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:
- Validate the patch, by searching for one of the patched artifacts. For example, if you had just upgraded JBoss Fuse 6.2.1 to the patch with build number
621423, you could search for bundles with this build number, as follows:
JBoss Fuse:karaf@root> osgi:list -s -t 0 | grep -i 630xxx [ 6] [Active ] [ ] [ ] [ 10] org.apache.felix.configadmin (1.2.0.redhat-630xxx)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
- 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 PatchIDIn 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.