1. Start an editing session by typing config:edit PID.
   PID is the PID for the configuration you are editing. It must be entered exactly. If it does not match the desired PID, the container will create a new PID with the specified name.
2. Remind yourself of the available properties in a particular configuration by typing config:proplist.
3. Use one of the editing commands to change the properties in the configuration.
   The editing commands include:
   • config:propappend—appends a new property to the configuration
   • config:propset—set the value for a configuration property
   • config:propdel—delete a property from the configuration
4. Update the configuration in memory and save it to disk by typing config:update.

Procedure 16.1. Stop JBoss Fuse saving Logging History on shutdown.

1. Stop JBoss Fuse.
2. Edit $FUSE_HOME/etc/system.properties.
3. Uncomment the line that says # karaf.shell.history.maxSize = 0 .
4. Restart JBoss Fuse

1. In each of your applications, edit the Java source code to define a unique application key.
   If you are using slf4j, add the following static method call to your application:

   org.slf4j.MDC.put("app.name","MyFooApp");

   If you are using log4j, add the following static method call to your application:

   org.apache.log4j.MDC.put("app.name","MyFooApp");

2. Edit the etc/org.ops4j.pax.logging PID to customize the sift appender.
   1. Set log4j.appender.sift.key to app.name.
   2. Set log4j.appender.sift.appender.file to =${karaf.data}/log/$\\{app.name\\}.log.
3. Edit the etc/org.ops4j.pax.logging PID to add the sift appender to the root logger.

   JBossFuse:karaf@root> config:edit org.ops4j.pax.logging
   JBossFuse:karaf@root> config:propset log4j.rootLogger "INFO, out, sift, osgi:VmLogAppender"
   JBossFuse:karaf@root> config:update

1. Identify which rollup patch you need to install and download it from the Customer Portal. For more details, see Section 19.2, “Finding the Right Patches to Apply”.
2. Unzip the rollup patch file to a convenient location, just as you would with a regular GA distribution. This is your new installation of JBoss Fuse.

1. Download the appropriate patch management package. From the JBoss Fuse 6.2.0 Software Downloads page, select a package named Red Hat JBoss Fuse 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-fuse-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

1. Make a full backup of your JBoss Fuse 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 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 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.

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.

1. Download the appropriate patch management package. From the JBoss Fuse 6.2.0 Software Downloads page, select a package named Red Hat JBoss Fuse 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

   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-fuse-620-TargetVersion.zip, on top of every Karaf container installation (root container, SSH containers, and so on). Use an archive utility to extract the contents on top of the existing 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 root container, if it is not already running.
4. Create a new version, using the fabric:version-create command (where we assume that the current profile version is 1.0):

   JBossFuse:karaf@root> fabric:version-create --parent 1.0 1.0.1
   Created version: 1.0.1 as copy of: 1.0

   Important

   Version names are important! The tooling sorts version names based on the numeric version string, according to major.minor numbering, to determine the version on which to base a new one. You can safely add a text description to a version name as long as you append it to the end of the generated default name like this: 1.3 [.description]. If you abandon the default naming convention and use a textual name instead (for example, Patch051312), the next version you create will be based, not on the last version (Patch051312), but on the highest-numbered version determined by dot syntax.
5. Update the patch property in the io.fabric8.version PID in the version 1.0.1 of the default profile, by entering the following Karaf console command:

   profile-edit --pid io.fabric8.version/patch=1.2.0.redhat-621xxx default 1.0.1

   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).
6. Reconfigure the Fabric agent so that the version of the patch mechanism it uses is determined by the patch version property (set in the previous step). Enter the following console command:

   profile-edit --pid 'io.fabric8.agent/repository.fabric8-patch=mvn:io.fabric8.patch/patch-features/${version:patch}/xml/features' default 1.0.1

7. Upgrade the root container to use the new patching mechanism, as follows:

   container-upgrade 1.0.1 root

8. Likewise, for all other containers in your fabric that need to be patched (SSH, child, and so on), provision them with the new patching mechanism by upgrading them to profile version 1.0.1. For example:

   container-upgrade 1.0.1 container1 container2 container3

1. Before applying the rollup patch to your fabric, you must patch the patch mechanism, as described in the section called “Patching the patch mechanism”.
2. For every top-level container (that is, any container that is not a child container), perform these steps, one container at a time:
   1. In the Karaf installation, 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).
   2. Restart the container.
3. Add the patch to the root container's environment using the patch:add command. For example, to add the patch.zip patch file:

   JBossFuse:karaf@root> patch:add file://patch.zip
   [name]            [installed] [description]                   
   PatchID         false       Description

   Important

   If you have decided to use a local repository to distribute the patch artifacts (recommended), set up the local repository now—see the section called “Distribution of patch artifacts”.
4. Create a new version, using the fabric:version-create command:

   JBossFuse:karaf@root> fabric:version-create 1.1
   Created version: 1.1 as copy of: 1.0.1

   Important

   Version names are important! The tooling sorts version names based on the numeric version string, according to major.minor numbering, to determine the version on which to base a new one. You can safely add a text description to a version name as long as you append it to the end of the generated default name like this: 1.3 [.description]. If you abandon the default naming convention and use a textual name instead (for example, Patch051312), the next version you create will be based, not on the last version (Patch051312), but on the highest-numbered version determined by dot syntax.
5. Apply the patch to the new version, using the patch:fabric-install command. Note that in order to run this command you must provide the credentials, Username and Password, of a user with Administrator privileges. For example, to apply the PatchID patch to version 1.1:

   patch:fabric-install --username Username --password Password --upload --version 1.1 PatchID

   Note

   When you invoke the patch:fabric-install command with the --upload option, Fabric looks up the ZooKeeper registry to discover the URL of the currently active Maven proxy, and uploads all of the patch artifacts to this URL. Using this approach it is possible to make the patch artifacts available through the Maven proxy, even if the container you are currently logged into is not hosting the Maven proxy.
6. Synchronize the patch information across the fabric, to ensure that the profile changes in version 1.1 are propagated to all containers in the fabric (particularly remote SSH containers). Enter the following console command:

   patch:fabric-synchronize

7. Upgrade each existing container in the fabric using the fabric:container-upgrade command (but leaving the root container, where you installed the patch, until last). For example, to upgrade a container named remote, enter the following command:

   JBossFuse:karaf@root> fabric:container-upgrade 1.1 remote
   Upgraded container remote from version 1.0.1 to 1.1

   At this point, not only does the Fabric agent download and install the patched bundles into the specified container, but the agent also applies the patch to the underlying container (updating any static files in the container, if necessary). If necessary, the agent will then restart the target container automatically or set the container status to requires full restart (if an automatic restart is not possible), so that any changes made to the static files are applied to the running container.
   Important

   It is recommended that you upgrade only one or two containers to the patched profile version, to ensure that the patch does not introduce any new issues.
8. If the current status of the upgraded container is requires full restart, you must now use one of the standard mechanisms to stop and restart the container manually. In some cases, it will be possible to do this using Fabric commands from the console of the root container.
   For example, you could stop the remote container as follows:

   fabric:container-stop remote

   And restart the remote container as follows:

   fabric:container-start remote

9. Upgrade the root container last (that is, the container that you originally installed the patch on):

   fabric:container-upgrade 1.1 root

10. (Windows only) If the root container status has changed to requires full restart and it is running on a Windows operating system, you must first shut down all of the root container's child containers (if any) before manually restarting the root container.
    For example, if the root container has three child containers, child1, child2, and child3, you would first shut them down, as follows:

    fabric:container-stop child1 child2 child3

    You can then shut down the root container with the shutdown command:

    shutdown

1. Before you proceed to install the incremental 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 incremental patch.
2. Create a new version, using the fabric:version-create command:

   JBossFuse:karaf@root> fabric:version-create 1.1
   Created version: 1.1 as copy of: 1.0

   Important

   Version names are important! The tooling sorts version names based on the numeric version string, according to major.minor numbering, to determine the version on which to base a new one. You can safely add a text description to a version name as long as you append it to the end of the generated default name like this: 1.3 <.description > .If you abandon the default naming convention and use a textual name instead (for example, Patch051312), the next version you create will be based, not on the last version (Patch051312), but on the highest-numbered version determined by dot syntax.
3. Apply the patch to the new version, using the fabric:patch-apply command. For example, to apply the activemq.zip patch file to version 1.1:

   JBossFuse:karaf@root> fabric:patch-apply --version 1.1 file:///patches/activemq.zip

4. Upgrade a container using the fabric:container-upgrade command, specifying which container you want to upgrade. For example, to upgrade the child1 container, enter the following command:

   JBossFuse:karaf@root> fabric:container-upgrade 1.1 child1
   Upgraded container child1 from version 1.0 to 1.1

   Important

   It is recommended that you upgrade only one or two containers to the patched profile version, to ensure that the patch does not introduce any new issues. Upgrade the root container (the one that you applied the patch to, using the fabric:patch-apply command) last.
5. You can check that the new patch profile has been created using the fabric:profile-list command, as follows:

   BossFuse:karaf@root> fabric:profile-list --version 1.1 | grep patch
   default                                  0              patch-activemq-patch
   patch-activemq-patch

   Where we presume that the patch was applied to profile version 1.1.
   Tip

   If you want to avoid specifying the profile version (with --version) every time you invoke a profile command, you can change the default profile version using the fabric:version-set-default Version command.
   You can also check whether specific JARs are included in the patch, for example:

   JBossFuse:karaf@root> list | grep -i activemq
   [ 131] [Active     ] [Created     ] [       ] [   50] activemq-osgi (5.9.0.redhat-61037X)
   [ 139] [Active     ] [Created     ] [       ] [   50] activemq-karaf (5.9.0.redhat-61037X)
   [ 207] [Active     ] [            ] [       ] [   60] activemq-camel (5.9.0.redhat-61037X)

1. Delete the org.ops4j.pax.url.mvn.repositories property setting from the io.fabric8.agent PID in the default profile, using the following console command:

   profile-edit --delete --pid io.fabric8.agent/org.ops4j.pax.url.mvn.repositories default

   When the repositories setting is absent, Fabric implicitly switches to the settings.xml configuration approach.
   Note

   This step simultaneously clears both the repositories list used by the Fabric8 agent and the repositories list used by the Maven proxy server (because the Maven proxy's repository list is normally copied straight from the Fabric8 agent's repository list).
2. Set the io.fabric8.maven.settings property from the io.fabric8.maven PID in the default profile to the location of the Maven settings.xml file. For example, if your settings.xml file is stored in the location, /home/fuse/settings.xml, you would set the io.fabric8.maven.settings property as follows:

   profile-edit --pid io.fabric8.maven/io.fabric8.maven.settings='/home/fuse/settings.xml' default

   Note

   The effect of this setting is to configure the Maven proxy server to takes its Maven configuration from the specified settings.xml file. The Fabric8 agent is not affected by this setting.
3. In order to configure the Fabric8 agent with the Maven settings.xml, set the org.ops4j.pax.url.mvn.settings property from the io.fabric8.agent PID in the default profile to the location of the Maven settings.xml file. For example, if your settings.xml file is stored in the location, /home/fuse/settings.xml, you would set the org.ops4j.pax.url.mvn.settings property as follows:

   profile-edit --pid io.fabric8.agent/org.ops4j.pax.url.mvn.settings='/home/fuse/settings.xml' default

   Important

   If you configure a HTTP proxy in your settings.xml file, it is essential to configure the ensemble hosts (where the Maven proxies are running) as HTTP non-proxy hosts. Otherwise, the Fabric8 agent tries to connect to the local Maven proxy through the HTTP proxy (which is an error).