Configuring and Running Fuse ESB Enterprise

Version 7.1

December 2012
Trademark Disclaimer
Third Party Acknowledgements

Updated: 08 Jan 2014

Revision History

Table of Contents

1. Configuring the Initial Features in a Standalone Container
2. Installing Fuse ESB Enterprise as a Service
Configuring the Wrapper
Installing and Starting the Service
3. Basic Security
Configuring Basic Security
Disabling Broker Security
4. Starting and Stopping Fuse ESB Enterprise
Starting Fuse ESB Enterprise
Stopping Fuse ESB Enterprise
5. Creating a New Fabric
6. Joining a Fabric
7. Using Remote Connections to Manage a Container
Configuring a Container for Remote Access
Connecting and Disconnecting Remotely
Connecting to a Standalone Container from a Remote Container
Connecting to a Fabric Container From another Fabric Container
Connecting to a Container Using the Client Command-Line Utility
Connecting to a Container Using the SSH Command-Line Utility
Stopping a Remote Container
8. Managing Child Containers
Standalone Child Containers
Fabric Child Containers
9. Configuring Fuse ESB Enterprise
Introducing Fuse ESB Enterprise Configuration
Setting OSGi Framework and Initial Container Properties
Configuring Standalone Containers Using the Command Console
Configuring Fabric Containers
10. Configuring the Hot Deployment System
11. Configuring JMX
12. Configuring JAAS Security
Alternative JAAS Realms
JAAS Console Commands
Standalone Realm Properties File
13. Logging
Logging Configuration
Logging per Application
Log Commands
14. Persistence
15. Failover Deployments
Using a Simple Lock File System
Using a JDBC Lock System
Container-level Locking
16. Configuring JBI Component Thread Pools
17. Applying Patches
Patching a Standalone Container
Patching a Container in a Fabric
18. Configuring a Fabric's Maven Proxy

List of Figures

3.1. Ports Exposed by the Fuse ESB Enterprise Container

List of Tables

2.1. Wrapper Logging Properties
9.1. Fuse ESB Enterprise Configuration Files
9.2. Properties for the OSGi Framework
9.3. Container Properties
11.1. JMX Access Properties
15.1. Bundle Start Levels
16.1. Component Thread Pool Properties

List of Examples

2.1. Default Environment Settings
2.2. Default Java System Properties
2.3. Default Wrapper Classpath
2.4. Wrapper JMX Properties
7.1. Changing the Port for Remote Access
7.2. ssh:ssh Command Syntax
7.3. Connecting to a Remote Console
7.4. Output of the shell:info Command
7.5. fabric:container-connect Command Syntax
7.6. Connecting to a Remote Container
7.7. Output of the shell:info Command
7.8. Karaf Client Help
7.9. stop Script Syntax
8.1. Creating a Runtime Instance
8.2. Listing Instances
8.3. Admin connect Command
8.4. The admin Script
9.1. Output of the config:list Command
9.2. Editing a Configuration
9.3. Editing Fabric Profile
10.1. Configuring the Hot Deployment Folders
13.1. Changing Logging Levels
13.2. Changing the Log Information Displayed on the Console
13.3. Enabling Per Bundle Logging
15.1. Lock File Failover Configuration
15.2. JDBC Lock File Configuration
15.3. JDBC Lock File Configuration for Oracle
15.4. JDBC Lock File Configuration for Derby
15.5. JDBC Lock File Configuration for MySQL
15.6. JDBC Lock File Configuration for PostgreSQL
15.7. Container-level Locking Configuration
16.1. Component Thread Pool Configuration
17.1. Adding a Patch to a Broker's Environment
17.2. Rolling Back a Patch
18.1. Configuring the Maven Proxy URL

Installing Fuse ESB Enterprise as a system service is a two step process:

  1. Configure the service wrapper for your system.

  2. Install the service wrapper as system service.

All of the Web consoles are installed as servlets in the container's embedded Jetty container. The Web consoles share the same HTTP server port, which is powered by Jetty. You can optionally enable the following Web consoles in Fuse ESB Enterprise:

  • Karaf Web console—is not installed by default. To enable the Karaf Web console, perform the following steps:

    1. In a running Fuse ESB Enterprise instance (see Starting Fuse ESB Enterprise), enter the following console command:

      karaf@root> features:install webconsole
    2. In a Web browser, navigate to the following URL:

    3. The browser will prompt you to log on. Enter valid JAAS user credentials to access the console.

  • Apache ActiveMQ Web console—is not installed by default. To enable the Apache ActiveMQ Web console, perform the following steps:

    1. Make sure that you have already configured the container's Java system properties, as described in Configure the Apache ActiveMQ Web console (optional).


      The Apache ActiveMQ Web console has a three tier architecture, as shown in Figure 3.1. The credentials provided in this step enable the middle tier (the Web console servlet) to log on to the back-end tier (the Apache ActiveMQ broker).

    2. In a running Fuse ESB Enterprise instance, enter the following console command:

      karaf@root> features:install mq-web-console
    3. In a Web browser, navigate to the following URL:

    4. The browser will prompt you to log on. Enter valid JAAS user credentials to access the console.

Launching in server mode runs Fuse ESB Enterprise in the background, without a local console. You would then connect to the running instance using a remote console. See Connecting and Disconnecting Remotely for details.

To launch Fuse ESB Enterprise in server mode, run the following


bin\fuseesb.bat server


bin/fuseesb server

Alternatively, you can launch Fuse ESB Enterprise in server mode using the start script in the InstallDir/bin directory.

You can stop an instance of Fuse ESB Enterprise either from within a console, or using a stop script.

If you launched Fuse ESB Enterprise by running fuseesb server or by running the start script, you can stop it remotely, as described in Stopping a Remote Container.

Alternatively, you can log on to the host where the instance is running and run one of the following from the InstallDir/bin directory:

  • ./admin stop instanceName

  • ./stop


If the sshHost property in etc/ is set to the default value of, you can run the stop script without any arguments. However, if you have configured a different hostname, you must run stop -h hostname.

A Fabric Ensemble is a collection of Fabric Servers and Fabric Containers that collectively maintain the state of the fabric registry. The Fabric Ensemble implements a replicated database and uses a quorum-based voting system to ensure that data in the fabric registry remains consistent across all of the fabric's containers. To guard against network splits in a quorum-based system, it is a requirement that the number of Fabric Servers in a Fabric Ensemble is always an odd number.

The number of Fabric Servers in a fabric is typically 1, 3, or 5. A fabric with just one Fabric Server is suitable for experimentation only. A live production system should have at least 3 or 5 Fabric Servers, installed on separate hosts, to provide fault tolerance.

To create a new fabric from a standalone container:

  1. Connect to the standalone container's command console.

  2. Any existing users in the InstallDir/etc/ file are automatically used to initialize the fabric's user data, when you create the fabric. This provides a convenient way to initialize the fabric's user data.

    If you have not already done so, it is recommended that you populate the file, by adding one or more lines of the following form:


    At least one of the users must have the admin role, to enable administration of the fabric. For example:

  3. Assuming that some users are already defined in the file, you can create a new fabric by entering the following command:

    FuseESB:karaf@root> fabric:create --zookeeper-password admin

    The current container (named root by default) becomes a Fabric Server with a registry service installed. Initially, this is the only container in the fabric. The Zookeeper password is used to protect sensitive data in the Fabric registry service (all of the nodes under /fabric).


    If you want to import a predefined set of profiles, use the -p import-dir option to specify the set of profiles to import.

    For more details on fabric:create see fabric:create in Console Reference.

  4. (Alternative) If no users are predefined in the file, an alternative approach is to define a new user at the same time the fabric is created, by supplying the --new-user and --new-user-password options, as follows:

    FuseESB:karaf@root> fabric:create --new-user jdoe --new-user-password secretpassword --zookeeper-password admin

    The new user, jdoe, is automatically assigned the admin role, which gives the user full administration privileges.

To join a container to a fabric, perform the following steps:

  1. Get the registry service URL for one of the Fabric Servers in the existing fabric. The registry service URL has the following format:


    Normally, it is sufficient to specify just the hostname, Hostname, because the registry service uses the fixed port number, 2182, by default. In exceptional cases, you can discover the registry service port by following the instructions in How to discover the URL of a Fabric Server.

  2. Get the ZooKeeper password for the fabric. An administrator can access the fabric's ZooKeeper password at any time, by entering the following console command (while logged into one of the Fabric Containers):

    karaf@root> fabric:ensemble-password
  3. Connect to the standalone container's command console.

  4. Join a container in one of the following ways:

    • Join as a managed container, with a default profile—uses the fabric profile.

      karaf@root> fabric:join --zookeeper-password ZooPass URL ContainerName
    • Join as a managed container, specifying a custom profile—uses a custom profile.

      karaf@root> fabric:join --zookeeper-password ZooPass -p Profile URL ContainerName
    • Join as a non-managed container—preserves the existing container configuration.

      karaf@root> fabric:join -n --zookeeper-password ZooPass URL ContainerName

    Where you can specify the following values:


    The existing fabric's ZooKeeper password.


    The URL for one of the fabric's registry services (usually just the hostname where a Fabric Server is running).


    The new name of the container when it registers itself with the fabric.


    If the container being added to the fabric has the same name as a container already registered with the fabric, both containers will be reset and will always share the same configuration.


    The name of the custom profile to install into the container after it joins the fabric (managed container only).

  5. If you joined the container as a managed container, you can subsequently deploy a different profile into the container using the fabric:container-change-profile console command (see ????).

When you start the Fuse ESB Enterprise runtime in default mode or in server mode, it enables a remote console that can be accessed over SSH from any other Fuse ESB Enterprise console. The remote console provides all of the functionality of the local console and allows a remote user complete control over the container and the services running inside of it.


When run in client mode the Fuse ESB Enterprise runtime disables the remote console.

You connect to a remote container's console using the ssh:ssh console command.

-l username

The username used to connect to the remote container. Use valid JAAS login credentials that have admin privileges (see Configuring JAAS Security).

-P password

The password used to connect to the remote container.

-p port

The SSH port used to access the desired container's remote console.

By default this value is 8101. See Configuring a standalone container for remote access for details on changing the port number.


The hostname of the machine that the remote container is running on. See Configuring a standalone container for remote access for details on changing the hostname.


We recommend that you customize the username and password in the etc/ file. See Configuring JAAS Securityfor details.

To confirm that you have connected to the correct container, type shell:info at the prompt. Information about the currently connected instance is returned, as shown in Example 7.4.

In the context of a fabric, you should connect to a remote runtime's console using the fabric:container-connect command.

-u username

The username used to connect to the remote console. The default value is admin.

-p password

The password used to connect to the remote console. The default value is admin.


The name of the container.


We recommend that you change the default administrator username and password. See Configuring JAAS Security for details.

To confirm that you have connected to the correct container, type shell:info at the prompt. Information about the currently connected instance is returned, as shown in Example 7.7.

The remote client allows you to securely connect to a remote Fuse ESB Enterprise container without having to launch a full Fuse ESB Enterprise container locally.

For example, to quickly connect to a Fuse ESB Enterprise instance running in server mode on the same machine, open a command prompt and run the client[.bat] script (which is located in the InstallDir/bin directory), as follows:


More usually, you would provide a hostname, port, username, and password to connect to a remote instance. If you were using the client within a larger script, for example in a test suite, you could append console commands as follows:

client -a 8101 -h hostname -u username -p password shell:info

Alternatively, if you omit the -p option, you will be prompted to enter a password.

For a standalone container, use any valid JAAS user credentials that have admin privileges.

For a container in a fabric, the default username and password is admin and admin.

To display the available options for the client, type:

client --help

To use the SSH key pair for logging into the Fuse ESB Enterprise container, you must install the SSH public key in the container by creating a new user entry in the InstallDir/etc/ file. Each user entry in this file appears on a single line, in the following format:


For example, given that your public key file, ~/.ssh/, has the following contents:

ssh-rsa AAAAB3NzaC1kc3MAAACBAP1/U4EddRIpUt9KnC7s5Of2EbdSPO9EAMMeP4C2USZpRV1AIlH7WT2NWPq/xfW6MPbLm1Vs14E7
7Y7TyhPdXh/0dthTRBy6bqGtRPxGa7gJov1xm/UuYYXPIUR/3x9MAZvZ5xvE0kYXO+rx jdoe@doemachine.local

You can create the jdoe user with the admin role by adding the following entry to the InstallDir/etc/ file (on a single line):


Do not insert the entire contents of the file here. Insert just the block of symbols which represents the public key itself.

You create a new runtime container by typing admin:create in the Fuse ESB Enterprise console.

As shown in Example 8.1, admin:create causes the container to create a new child container in the active container's instances/containerName directory. The new container is a direct copy of its parent. The only difference between parent and child is the port number they listen on. The child container is assigned an SSH port number based on an incremental count starting at 8101.

You can configure the Fuse ESB Enterprise runtime using the following files:

Table 9.1. Fuse ESB Enterprise Configuration Files

activemq.xmlConfigures the defaultApache ActiveMQ broker in a Fabric (used in combination with the file).
config.propertiesThe main configuration file for the container See Setting OSGi Framework and Initial Container Properties for details.
keys.propertiesLists the users who can access the Fuse ESB Enterprise runtime using the SSH key-based protocol. The file's contents take the format username=publicKey,role
org.apache.aries.transaction.cfgConfigures the transaction feature
org.apache.felix.fileinstall-deploy.cfgConfigures a watched directory and polling interval for hot deployment.
org.apache.karaf.features.cfgConfigures a list of feature repositories to be registered and a list of features to be installed when Fuse ESB Enterprise starts up for the first time.
org.apache.karaf.features.obr.cfgConfigures the default values for the features OSGi Bundle Resolver (OBR).
org.apache.karaf.jaas.cfgConfigures options for the Karaf JAAS login module. Mainly used for configuring encrypted passwords (disabled by default).
org.apache.karaf.log.cfgConfigures the output of the log console commands. See Logging Configuration.

Configures the JMX system. See Configuring JMX for details.

Configures the properties of remote consoles. For more information see Configuring a Container for Remote Access.


Configures the shutdown timeout for the JBI container.


Configures the default thread pool settings for JBI. See Old Mechanism not supported.


Configures the thread pool settings specifically for the Name JBI component. See Old Mechanism not supported.

org.fusesource.bai.agent.cfgConfigures the Fuse BAI (Business Activity Insight) feature, if it is installed.
org.fusesource.fabric.fab.osgi.url.cfgConfigures the Maven repositories used by the Fuse Application Bundle (FAB) runtime when downloading artifacts. If the properties in this file are not set, FAB defaults to the values in org.ops4j.pax.url.mvn.cfg.
org.fusesource.fabric.maven.cfgConfigures the Maven repositories used by the Fabric Maven Proxy when downloading artifacts, (The Fabric Maven Proxy is used for provisioning new containers on a remote host.) the defaultApache ActiveMQ broker in a Fabric (used in combination with the activemq.xml file). options for formatting the output of jclouds:* console commands.

Configures the logging system. For more, see Logging Configuration.

org.ops4j.pax.url.mvn.cfgConfigures additional URL resolvers.
org.ops4j.pax.web.cfgConfigures the default Jetty container (Web server). See Securing the Web Console in Security Guide.

Specifies which bundles are started in the container and their start-levels. Entries take the format bundle=start-level.

Specifies Java system properties. Any properties set in this file are available at runtime using System.getProperties(). See Setting System and Config Properties for more.

users.propertiesLists the users who can access the Fuse ESB Enterprise runtime either remotely or via the web console. The file's contents take the format username=password,role

The config:list command will show all of the PIDs currently in use by the container. As shown in Example 9.1, the output from config:list contains all of the PIDs and all of the properties for each of the PIDs.

Listing the container's configuration is a good idea before editing a container's configuration. You can use the output to ensure that you know the exact PID to change.

In a standalone container, use any valid JAAS user credentials (see Create a secure JAAS user).

In a fabric, the default username is admin and the default password is admin.

You can change the username and password used to connect to the JMX server by configuring the JAAS security system as described in Configuring JAAS Security.

A standalone container (which uses the JAAS PropertiesLoginModule and the PublickeyLoginModule) maintains its own database of secure user data, independently of any other containers. To configure the user data for a standalone container, you must log into the specific container (see Connecting and Disconnecting Remotely) whose data you want to modify. Each standalone container must be configured separately.

To start editing the standalone JAAS user data, you must first specify the JAAS realm that you want to modify. To see the available realms, enter the jaas:realms command, as follows:

karaf@root> jaas:realms
Index Realm                Module Class                                                                    
    1 karaf                        
    2 karaf                org.apache.karaf.jaas.modules.publickey.PublickeyLoginModule

Both of these login modules are active in the default karaf JAAS realm. Enter the following console command to start editing the properties login module in the karaf realm:

karaf@root> jaas:manage --index 1

Fuse ESB Enterprise uses the OPS4j Pax Logging system. Pax Logging is an open source OSGi logging service that extends the standard OSGi logging service to make it more appropriate for use in enterprise applications. It uses Apache Log4j as the back-end logging service. Pax Logging has its own API, but it also supports the following APIs:

  • Apache Log4j

  • Apache Commons Logging

  • SLF4J

  • Java Util Logging

For more information on OPS4j Pax Logging see

Example 16.1 shows the configuration for a component whose thread pool can have between 10 and 200 threads.

Incremental patching allows you apply targets fixes to a container without needing to reinstall an updated version of Fuse ESB Enterprise. It also allows you to easily back the patch out if it causes problems with your deployed applications.

Patches are ZIP files that contain the artifacts needed to update a targeted set of bundles in a container. The patch file includes a .patch file that lists the contained artifacts. The artifacts are typically one or more bundles. They can, however, include configuration files and feature descriptors.

You get a patch file in one of the following ways:

  • Customer Support sends you a patch.

  • Customer Support sends you a link to download a patch.

The process of applying a patch to a container depends on how the container is deployed:

  • standalone—the container's command console's patch shell has commands for managing the patching process

  • fabric—patching a fabric requires applying the patch to a profile and then applying the profile to a container

    Fuse Management Console is the recommended way to patch containers in a fabric. See the Fuse Management Console patching documentation for more information.

Patching a standalone container directs the container to load the patch versions of artifacts instead of the non-patch versions. The patch shell provides commands to patches to the container's environment, see which bundles are effected by applying the patch, apply the patch to the container, and back the patch out if needed.

To make sure that the a patch can be rolled back Fuse ESB Enterprise applies the patch in a non-destructive manner. The patching process does not overwrite the artifacts included in the original installation. The patched artifacts are placed in the container's system folder. When the patch is applied, the container's configuration is changed so that it points to the patched artifacts instead of the artifacts from the original installation. This makes it easy for the system to be restored to its original state or to selectively back out patches.


Patches do not persist across installations. If you delete and reinstall a Fuse ESB Enterprise instance you will need to download the patches and reapply them.

To apply a patch to a standalone container:

  1. Make sure you install all the Apache Karaf features you need before you start to install the patch. If you install any features after installing the patch, the features will install the original unpatched versions of the dependencies—see Adding features to a patched container.

  2. Add the patch to the container's environment using the patch:add command.

    Example 17.1 shows the command for adding the patch contained in the patch file from the local file system.

    This command copies the specified patch file to the container's system folder and unpacks it.

  3. 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.


    The patch:list command will display a list of all patches added to the container's system folder.

  4. Review the simulation log to understand the changes that will be made to the container.

  5. Apply the patch to the container using the patch:install command.


    Running patch:install before the container is fully started and all of the bundles are active will cause the container to hang.


    The patch:list command will display a list of all patches added to the container's system folder.

The container will need to restart to apply the patch. If you are using a remote console, you will lose the connection to the container. If you are using the container's local console, it will automatically reconnect when the container restarts.

The Fabric Ensemble creates a Maven proxy to facilitate access to the artifacts required the containers in the fabric. Each Fabric Server deployed in the fabric runs an instance of a Maven proxy. The ensemble aggregates all of the proxies so that it appears to the Fabric Agents as a single Maven proxy.


Advanced users can configure each Fabric Server to act as a proxy for a different set of repositories. However, this is not a recommended set up.

The Fabric Agents use the fabric's Maven proxy to access the known repositories. This ensures that all of the containers use the same set of repositories and artifacts.


Fuse IDE provides tooling for uploading bundles using the Maven proxy. You can also add the fabric's Maven Proxy to a POM file so that bundles can be distributed to the ensemble as part of an automated build process.

To change the repositories the ensemble proxies:

  1. Create a new profile version.

    From the command console this is done using the fabric:version-create command. See fabric:version-create in Console Reference for more information.

  2. Change the org.ops4j.pax.url.mvn.repositories property in the org.fusesource.fabric.agent PID of the default profile. Example 18.1 shows the console command for editing this property.


    The org.fusesource.fabric.agent PID is refined in all of the fabric profiles. Setting the proxy URL, the org.ops4j.pax.url.mvn.repositories property, in the default profile ensures that all of the other fabric profiles share the same Maven proxy setting.


    The fabric profile's org.fusesource.fabric.maven PID, which ultimately controls the Maven proxy, imports its value from the default profile's org.fusesource.fabric.agent PID. You should not change the settings of the org.fusesource.fabric.maven PID.

  3. Roll the changes out the fabric by upgrading the containers to the new profile version.


    You cannot test this configuration change out on a few containers to validate it. The change must be made to the entire fabric or it will result in conflicts.


org.apache.felix.fileinstall-deploy, Overview
org.apache.karaf.log, Overview
org.fusesource.fabric.agent, Changing the repositories
org.fusesource.fabric.maven, Changing the repositories
org.ops4j.pax.logging, Overview
org.ops4j.pax.logging.DefaultServiceLog.level, Overview
org.ops4j.pax.url.mvn.repositories, Changing the repositories, Changing the bundle cache location, Flushing the bundle cache
org.osgi.service.http.port, Initial container properties
configuration, Introducing Fuse ESB Enterprise Configuration
OSGi framework
configuring, OSGi framework properties


patch:add, Applying a patch
patch:install, Applying a patch
patch:list, Applying a patch, Rolling back a patch
patch:rollback, Rolling back a patch
patch:simulate, Applying a patch
command console, Using the command console
Fuse Management Console, Using Fuse Management Console
standalone, Applying a patch
rollback, Rolling back a patch