Red Hat Training

A Red Hat training course is available for Red Hat Fuse

Chapter 4. Migrating JBoss Fuse from 6.2.0 to 6.2.1 on Karaf

Abstract

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

Overview

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:
  1. 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.
  2. 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.

Initial system

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 etc/ directory.
Note
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:
patch-management-for-fuse-620-6.2.1.redhat-084.zip
Available as the download file, Red Hat JBoss Fuse 6.2.1 on Karaf Update Installer.
jboss-fuse-full-6.2.1.redhat-084.zip
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:
  1. 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.cfg file, 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.
  2. 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.jar
    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. 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 patch
    The 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).
  5. 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.
  6. 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-084
    Note
    In 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.
  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. Apply the patch to the container using the patch:install command: 
    patch:install jboss-fuse-full-6.2.1.redhat-084
    Note
    Make sure that the container has fully started before you run patch:install.
  9. After installing the patch, the container shuts down automatically. At this point, the data/cache directory 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.bat script (which calls the bin\karaf.bat script) will output an error as it exits. This error can be safely ignored. This happens because, on Windows, the bin\karaf.bat script continues to execute even after it has been overwritten by the patch:install command (whereas on Linux or UNIX, the corresponding script process exits immediately).
  10. Open the bin/setenv file (bin\setenv.bat on Windows O/S) in a text editor and check the value of the JAVA_MAX_MEM environment variable, which must be set to at least 1024M. Increase the setting, if necessary.
    Note
    The JBoss Fuse 6.2.1 rollup patch tries to update the JAVA_MAX_MEM setting to the correct value. But if you have already customized the setenv file yourself, the patching mechanism preserves your custom settings. This could result in the JAVA_MAX_MEM environment variable having a value that is too low.
  11. The JBoss Fuse 6.2.1 rollup patch over-writes the contents of the etc/org.ops4j.pax.logging.cfg configuration 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.
  12. Restart the container manually, as follows: 
    ./bin/fuse
    As 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.
    Tip
    If you were invoking the scripts from within the InstallDir/bin directory, 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.