Language and Page Formatting Options
Chapter 4. Migrating JBoss Fuse from 6.2.0 to 6.2.1 on Karaf
If you have already deployed an instance of JBoss Fuse 6.2.0 Apache Karaf container, you can upgrade your 6.2.0 installation to version 6.2.1 using the new patching mechanism. The procedure for migrating a standalone container is different from the procedure for migrating a collection of Fabric containers. Follow the appropriate set of instructions for your system.
4.1. Patching a Standalone Karaf Container from 6.2.0 to 6.2.1
The instructions in this section are for upgrading an existing JBoss Fuse 6.2.0 Apache Karaf installation, which is deployed as a standalone container (in other words, not using Fabric), to version 6.2.1.
New patching mechanism
Upgrading from JBoss Fuse 6.2.0 to 6.2.1 requires the new patching mechanism, which is implemented for the first time in 6.2.1. This presents a bootstrapping problem: the existing 6.2.0 installation must be enhanced to support the new patching mechanism before you can install patch version 6.2.1. The upgrade procedure therefore consists of two distinct phases, as follows:
- Install the patch management enablement pack for 6.2.0, which replaces the existing patch mechanism with the new patching mechanism. In all other respects, the container remains at version 6.2.0.
- Install the 6.2.1 patch in the standalone container using the new patch mechanism. After this step, the container is upgraded fully to version 6.2.1.
The starting point for this patching procedures is assumed to be an installation of Red Hat JBoss Fuse 6.2.0 Full Install (
jboss-fuse-full-6.2.0.redhat-133.zip). This can be a container instance that you have customized in various ways, by adding application bundles and features, or even by editing configuration files under the
The new patching process is usually non-destructive, preserving any customizations made before the patch was applied. If a merge conflict cannot be resolved automatically, however, warning messages will be generated in the log file.
Download the required packages
To patch JBoss Fuse from 6.2.0 to 6.2.1 you require the following packages:
- Available as the download file, Red Hat JBoss Fuse 6.2.1 on Karaf Update Installer.
- Available as the download file, Red Hat JBoss Fuse 6.2.1 on Karaf Installer.
Applying the 6.2.1 patch to a standalone container
To upgrade a JBoss Fuse 6.2.0 standalone container to version 6.2.1, proceed as follows:
- Make a full backup of your JBoss Fuse 6.2.0 installation before attempting to apply the patch. In particular, if you made any custom changes to the
etc/org.ops4j.pax.logging.cfgfile, make sure that you back it up. The patch process for 6.2.1 will over-write this file and you will need to re-apply your changes to it.
- Install the patch management enablement pack for 6.2.0,
patch-management-for-fuse-620-6.2.1.redhat-084.zip, on top of your 6.2.0 installation. Use an archive utility to extract the contents on top of the existing 6.2.0 installation.The patch management enablement pack contains the following files:
patches/jboss-fuse-full-6.2.0.redhat-133-baseline.zip system/io/fabric8/patch/patch-commands/1.2.0.redhat-621084/patch-commands-1.2.0.redhat-621084.jar system/io/fabric8/patch/patch-management/1.2.0.redhat-621084/patch-management-1.2.0.redhat-621084.jar system/io/fabric8/patch/patch-features/1.2.0.redhat-621084/patch-features-1.2.0.redhat-621084-features.xml system/io/fabric8/patch/patch-core/1.2.0.redhat-621084/patch-core-1.2.0.redhat-621084.jarNoteIt does not matter whether the container is running or not when you extract these files.
- Start the container, if it is not already running.
- Enable the new patch management commands in the old 6.2.0 container, by entering the following console commands:
features:uninstall patch features:removeurl mvn:io.fabric8.patch/patch-features/1.2.0.redhat-133/xml/features features:addurl mvn:io.fabric8.patch/patch-features/1.2.0.redhat-621084/xml/features features:install patchThe effect of this is to replace the old patch commands by the new patch commands in the existing 6.2.0 container, thereby bootstrapping the new patch mechanism (which is needed to install the 6.2.1 patch).
- Before proceeding to the next phase, verify that the new patch commands have been successfully installed. Enter the following command:
JBossFuse:karaf@root> list -s -t 0 | grep -i patch [ 265] [Active ] [ ] [ ] [ 2] io.fabric8.patch.patch-management (1.2.0.redhat-621084) [ 266] [Active ] [ ] [ ] [ 80] io.fabric8.patch.patch-core (1.2.0.redhat-621084) [ 267] [Active ] [ ] [ ] [ 80] io.fabric8.patch.patch-commands (1.2.0.redhat-621084)Check that the preceding bundles and only these bundles are output by this command.
- Add the 6.2.1 patch to the container's environment using the patch:add command (remembering to customize the path to the patch file), as follows:
JBossFuse:karaf@root> patch:add file:///path/to/jboss-fuse-full-6.2.1.redhat-084.zip [name] [installed] [description] jboss-fuse-full-6.2.1.redhat-084 false jboss-fuse-full-6.2.1.redhat-084NoteIn this case, the patch file is the full distribution of JBoss Fuse 6.2.1. Under the new patching mechanism, the full distribution file has a dual purpose: you can extract the archive directly to create a fresh 6.2.1 distribution; or you can add the file as a patch to migrate an existing 6.2.0 installation to 6.2.1.
- 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.
- Apply the patch to the container using the patch:install command:
patch:install jboss-fuse-full-6.2.1.redhat-084NoteMake sure that the container has fully started before you run patch:install.
- After installing the patch, the container shuts down automatically. At this point, the
data/cachedirectory is empty, but it will be repopulated when the container starts up again.Note(Windows O/S only) At this point, it is likely that the
bin\fuse.batscript (which calls the
bin\karaf.batscript) will output an error as it exits. This error can be safely ignored. This happens because, on Windows, the
bin\karaf.batscript continues to execute even after it has been overwritten by the
patch:installcommand (whereas on Linux or UNIX, the corresponding script process exits immediately).
- Open the
bin\setenv.baton Windows O/S) in a text editor and check the value of the
JAVA_MAX_MEMenvironment variable, which must be set to at least
1024M. Increase the setting, if necessary.NoteThe JBoss Fuse 6.2.1 rollup patch tries to update the
JAVA_MAX_MEMsetting to the correct value. But if you have already customized the
setenvfile yourself, the patching mechanism preserves your custom settings. This could result in the
JAVA_MAX_MEMenvironment variable having a value that is too low.
- The JBoss Fuse 6.2.1 rollup patch over-writes the contents of the
etc/org.ops4j.pax.logging.cfgconfiguration file (in order fix a security issue). If you previously made any customizations to this file, they will be over-written. If this is the case, edit the file to re-apply your changes.
- Restart the container manually, as follows:
./bin/fuseAs the container starts up again, the patching mechanism repopulates the container with all of the requisite bundles and features for the patched standalone container. When the Welcome banner appears, it displays the new patch version:
_ ____ ______ | | _ \ | ____| | | |_) | ___ ___ ___ | |__ _ _ ___ ___ _ | | _ < / _ \/ __/ __| | __| | | / __|/ _ \ | |__| | |_) | (_) \__ \__ \ | | | |_| \__ \ __/ \____/|____/ \___/|___/___/ |_| \__,_|___/\___| JBoss Fuse (6.2.1.redhat-084) http://www.redhat.com/products/jbossenterprisemiddleware/fuse/ Hit '<tab>' for a list of available commands and '[cmd] --help' for help on a specific command. Open a browser to http://localhost:8181 to access the management console Create a new Fabric via 'fabric:create' or join an existing Fabric via 'fabric:join [someUrls]' Hit '<ctrl-d>' or 'osgi:shutdown' to shutdown JBoss Fuse.TipIf you were invoking the scripts from within the
InstallDir/bindirectory, you might find that the
bin/directory appears to be empty after the container shuts down. This is because the contents of this directory were re-written by the patch. To see the scripts again, simply re-enter the
bin/directory, for example:
cd ..;cd bin.