LibraryPrintFeedback

Managing and Monitoring a Broker

Version 7.1

December 2012
Trademark Disclaimer
Third Party Acknowledgements

Updated: 07 Jan 2014

Revision History

Table of Contents

1. Introduction
2. Editing a Broker's Configuration
Understanding the Fuse MQ Enterprise Configuration Model
Editing a Standalone Broker's Configuration
Editing a Broker's Configuration in a Fabric
3. Security Basics
Fuse MQ Enterprise Security Overview
Basic Security Configuration
Disabling Broker Security
4. Setting up and Accessing the Fuse MQ Enterprise Web Console
Using the Embedded Console
Securing the Web Console
Deploying a Standalone Console
5. Installing Fuse MQ Enterprise as a Service
Configuring the Wrapper
Installing and Starting the Service
6. Starting a Broker
7. Securing the Fuse MQ Enterprise Container
Defining JAAS Realms
Enabling LDAP Authentication
Using Encrypted Property Placeholders
Configuring Roles for the Administrative Protocols
8. Sending Commands to the Broker
9. Deploying a New Broker
Deploying a Standalone Broker
Deploying a New Broker into a Fabric
10. Shutting Down a Broker
Shutting Down a Local Broker
Shutting Down a Broker Remotely
11. Connecting a Broker to a Fabric
Joining a Broker to a Fabric
Joining a Fabric as a Managed Container
Joining a Fabric as a Non-Managed Container
Creating a New Fabric
12. Using Logging
Logging Configuration
Viewing the Log
13. Using JMX
Configuring JMX
Statistics Collected by JMX
Managing the Broker with JMX
14. Applying Patches
Patching a Standalone Broker
Patching a Broker in a Fabric
A. Required JARS
Index

List of Figures

2.1. Fuse MQ Enterprise Configuration System
3.1. Ports Exposed by the Fuse MQ Enterprise Container

List of Tables

5.1. Wrapper Logging Properties
6.1. Start up Commands for Console Mode
6.2. Start up Commands for Daemon Mode
7.1. Flags for Defining a JAAS Module
7.2. Properties for the Fuse MQ Enterprise LDAP Login Module
8.1. Administration Client Arguments
13.1. Broker JMX Configuration Properties
13.2. Broker JMX Statistics
13.3. Destination JMX Statistics
13.4. Connection JMX Statistics
13.5. Broker MBean Operations
13.6. Connector MBean Operations
13.7. Network Connector MBean Operations
13.8. Queue MBean Operations
13.9. Topic MBean Operations
13.10. Subscription MBean Operations

List of Examples

2.1. Adding Property Placeholder Support to Fuse MQ Enterprise Configuration
2.2. Configuration with Property Placeholders
2.3. Importing an XML Configuration Template
2.4. Creating a Profile Using an XML Configuration Template
2.5. Creating a Deployment Profile
2.6. Setting Properties in a Profile
2.7. Setting the Broker Name Property
2.8. Assigning a Profile to a Broker
4.1. Changing the Web Console's Port
4.2. SSL Enabled Web Console Configuration
4.3. Disabling the Embedded Web Console
4.4. Configuration for Deploying the Web Console in Tomcat
4.5. Configuration for Monitoring a Cluster with the Web Console
5.1. Default Environment Settings
5.2. Default Java System Properties
5.3. Default Wrapper Classpath
5.4. Wrapper JMX Properties
6.1. Broker Console
6.2. Starting a Broker in a Fabric
6.3. Starting a Broker in a Fabric with the Administration Client
7.1. JAAS Blueprint Namespace
7.2. Defining a JAAS Realm in Blueprint XML
7.3. Standard JAAS Properties
7.4. Blueprint JAAS Properties
7.5. Configuring a JAAS Realm
7.6. Fuse ESB Enterprise LDAP JAAS Login Module
7.7. Configuring a JAAS Realm that Uses LDAP Authentication
7.8. Property File with an Encrypted Property
7.9. Encrypted Property Namespaces
7.10. Aries Placeholder Extension
7.11. Jasypt Blueprint Configuration
7.12. Jasypt Blueprint Configuration
7.13. Installing the Jasypt Feature
8.1. Client Command
8.2. Console Help
8.3. Help for a Command
9.1. Uploading a Template to a Fabric Ensemble
9.2. Creating a New Broker in an Existing Container
9.3. Creating a New Broker in a New Container
9.4. Editing a Broker Profile
10.1. Using the Console's Shutdown Command
10.2. Stop Command Syntax
10.3. Stopping a Remote Broker
10.4. Shutting DOwn a Broker using a Remote Console Connection
10.5. Shutting Down a Broker in a Fabric
12.1. Changing Logging Levels
12.2. Changing the Log Information Displayed on the Console
13.1. Configuring a Broker's JMX Connection
14.1. Adding a Patch to a Broker's Environment
14.2. Rolling Back a Patch

There are a number of tools that you can use to monitor and administer Fuse MQ Enterprise.

The following tools are included with Fuse MQ Enterprise:

  • administration client—a command line tool that can be used to manage a broker and do rudimentary metric reporting

  • console mode—a runtime mode that presents you with a custom console that provides a number of administrative options

  • Web console—a browser based console that provides metric reporting, destination browsing, and other administrative functions

Red Hat also provides management tools that you can install as part of your subscription:

  • Fuse Management Console—a browser based console for viewing, monitoring, and deploying broker clusters

  • Fuse HQ—an advanced monitoring and management tool that can provide detailed metrics and alerting.

In addition to the Red Hat supplied tools there are a number of third party tools that can be used to administer and monitor a broker including:

  • jconsole—a JMX tool that is shipped with the JDK

  • VisualVM—a visual tool integrating several command line JDK tools and lightweight profiling capabilities

Configuring a broker involves making changes to a number of properties that are stored in multiple locations including:

  • an XML configuration file

  • OSGi persistent identifier properties

How you make the changes depends on how the broker is deployed:

  • standalone—if a broker is deployed as a standalone entity and not a part of a fabric, you change the configuration using a combination of directly editing the broker's configuration template file and the console's config shell.

  • in a fabric—if a broker is deployed into a fabric its configuration is managed by the Fabric Agent which draws all of the configuration from the fabric's registry. To modify the container of a broker running as part of a fabric, you need to modify the profile(s) deployed into it. You can do this by using either the fabric:profile-edit console command or Fuse Management Console.

[Note]Note

Many of the configuration properties are managed by the OSGi Admin Service and are organized by persistent identifier or PID. The container services look in a specific PID for particular properties, so it is important to set the properties in the correct PID.

The Fuse MQ Enterprise configuration template is an XML file that is based on the Apache ActiveMQ configuration file. The main differences between an Apache ActiveMQ and a Fuse MQ Enterprise configuration template are:

  • configuration templates use property placeholders for settings that will be controlled via the OSGi Admin service

  • configuration templates do not configure the broker's name

  • configuration templates do not configure the location of the data directory

  • configuration templates do not configure transport connectors

  • configuration templates do not configure network connectors

  • configuration templates do not control if a broker is a master or a slave node

  • configuration templates can be used as a baseline for multiple brokers on the same machine

The networking properties and role in a master/slave group are specified by the broker's PID and do not need to appear in the template. The broker's name and data directory are replaced in the template with property placeholders. Property placeholders can also be substituted for any attribute value or element value in the XML configuration. This allows the OSGi Admin system populate them from the broker's PID.

Property placeholders are specified using the syntax ${propName} and are resolved by matching properties in the broker's PID. In order to use property placeholder the configuration template must include the bean definition shown in Example 2.1.


The configuration template shown in Example 2.2 uses three property placeholders that allow you to modify the base configuration using fabric properties.


The default broker configuration template is etc/activemq.xml. You can the location of the configuration template by changing the config property in the broker's etc/org.fusesource.mq.fabric.server-default.cfg file.

The template can be edited using any text or XML editor.

The broker must be restarted for any changes in the template to take effect.

The recommended approach to configuring brokers in a fabric is:

  1. Create a configuration template.

  2. Create a base profile for all of the brokers in the fabric using the configuration template.

  3. Create profiles that inherit from the base profile that will be assigned to one or more brokers.

  4. Modify the properties in each of the profiles to the desired values for the brokers to which the profile will be assigned.

  5. Assign the new profiles to the desired brokers.

You should always create new profiles or a new version of the existing profiles before making configuration changes. Changes to profiles that are assigned to running brokers take effect immediately. Using new profiles, or a new version, allows you make the changes and test them on a subset of your brokers before rolling the changes to the entire fabric.

The Fuse MQ Enterprise Web console is an embedded console for administering standalone broker. Using the embedded console is an easy way to manage your broker with minimal configuration.

[Warning]Warning

Because the default configuration profile of a broker deployed into a Fabric container does not include the Web console, you must use Fuse Management Console to monitor fabric-deployed brokers, unless you install the a-mq profile in the Fabric container when you create the fabric. To do so, use the command fabric:create -p a-mq.

If you want more security, more reliability, or the ability to monitor master/slave clusters, you can deploy the Web console as a standalone application. It is easy to deploy into Tomcat or any standard Web container.

For a standalone broker the default configuration is for the Web console to be loaded along with the broker. The default address for the standalone broker's console is localhost:8181/activemqweb.

[Warning]Warning

Because the default configuration profile of a broker deployed into a Fabric container does not include the Web console, you must use Fuse Management Console to monitor fabric-deployed brokers, unless you install the a-mq profile in the Fabric container when you create the fabric. To do so, use the command fabric:create -p a-mq.

The default port and security configuration can easily be modified.

To enable SSL security on the Jetty server, edit the Connector bean in the conf/jetty.xml file. Replace the org.eclipse.jetty.server.nio.SelectChannelConnector class with the org.eclipse.jetty.server.ssl.SslSelectChannelConnector class. Specify the relevant properties of the SslSelectChannelConnector class in order to configure the Jetty server's HTTPS port as shown in Example 4.2.


The SslSelectChannelConnector properties can be explained as follows:

When SSL security is configured as shown, you can access the Web console through the HTTPS protocol using the URL https://localhost:8443/admin.

[Warning]Warning

The broker.ks certificate used in the example is insecure. Anyone can access its private key. To secure your system properly, you must create new certificates signed by a trusted CA, as described in Managing Certificates in Security Guide.

Installing Fuse MQ 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.

When defining a JAAS realm in the OSGi container, you cannot put the definitions in a conventional JAAS login configuration file. Instead, the OSGi container uses a special jaas:config element for defining JAAS realms in a blueprint configuration file. The JAAS realms defined in this way are made available to all of the application bundles deployed in the container, making it possible to share the JAAS security infrastructure across the whole container.

The syntax for the jaas:config element is shown in Example 7.2.


The elements are used as follows:

jaas:config

Defines the JAAS realm. It has the following attributes:

  • name—specifies the name of the JAAS realm.

  • rank—specifies an optional rank for resolving naming conflicts between JAAS realms . When two or more JAAS realms are registered under the same name, the OSGi container always picks the realm instance with the highest rank.

jaas:module

Defines a JAAS login module in the current realm. jaas:module has the following attributes:

The contents of a jaas:module element is a space separated list of property settings, which are used to initialize the JAAS login module instance. The specific properties are determined by the JAAS login module and must be put into the proper format.

[Note]Note

You can define multiple login modules in a realm.

Fuse ESB Enterprise uses the same properties as a standard Java login configuration file, however Fuse ESB Enterprise requires that they are specified slightly differently. To see how the Fuse ESB Enterprise approach to defining JAAS realms compares with the standard Java login configuration file approach, consider how to convert the login configuration shown in Example 7.3, which defines the PropertiesLogin realm using the Fuse MQ Enterprise properties login module class, PropertiesLoginModule:


The equivalent JAAS realm definition, using the jaas:config element in a blueprint file, is shown in Example 7.4.


[Important]Important

You do not use double quotes for JAAS properties in the blueprint configuration.

Table 7.2 describes the properties used to configure the Fuse MQ Enterprise JAAS LDAP login module.

Table 7.2. Properties for the Fuse MQ Enterprise LDAP Login Module

PropertyDescription
connection.url Specifies specify the location of the directory server using an ldap URL, ldap://Host:Port. You can optionally qualify this URL, by adding a forward slash, /, followed by the DN of a particular node in the directory tree.
connection.username Specifies the DN of the user that opens the connection to the directory server. For example, uid=admin,ou=system.
connection.password Specifies the password that matches the DN from connection.username. In the directory server, the password is normally stored as a userPassword attribute in the corresponding directory entry.
user.base.dn Specifies the DN of the subtree of the DIT to search for user entries.
user.filter Specifies the LDAP search filter used to locate user credentials. It is applied to the subtree selected by user.base.dn. Before being passed to the LDAP search operation, the value is subjected to string substitution such that all occurrences of %u are replaced by the user name extracted from the incoming credentials.
user.search.subtree Specifies if the user entry search's scope includes the subtrees of the tree selected by user.base.dn.
role.base.dn Specifies the DN of the subtree of the DIT to search for role entries.
role.filter Specifies the LDAP search filter used to locate roles. It is applied to the subtree selected by role.base.dn. Before being passed to the LDAP search operation, the value is subjected to string substitution such that all occurrences of %u are replaced by the user name extracted from the incoming credentials.
role.name.attribute Specifies the attribute type of the role entry that contains the name of the role/group. If you omit this option, the role search feature is effectively disabled.
role.search.subtree Specifies if the role entry search's scope includes the subtrees of the tree selected by role.base.dn.
authentication

Specifies the authentication method used when binding to the LDAP server. Valid values are

  • simple—bind with user name and password authentication

  • none—bind anonymously

initial.context.factory Specifies the class of the context factory used to connect to the LDAP server. This must always be set to com.sun.jndi.ldap.LdapCtxFactory.
ssl Specifies if the connection to the LDAP server is secured via SSL. If connection.url starts with ldaps:// SSL is used regardless of this property.
ssl.provider Specifies the SSL provider to use for the LDAP connection. If not specified, the default SSL provider is used.
ssl.protocol Specifies the protocol to use for the SSL connection.
ssl.algorithm Specifies the algorithm used by the trust store manager.
ssl.keystore Specifies the keystore name.
ssl.keyalias Specifies the name of the private key in the keystore.
ssl.truststore Specifies the trust keystore name.

All of the properties are mandatory except the SSL properties.

The placeholder you use for encrypted properties are the same as you use for regular properties. The use the form ${prop.name}.

Example 7.12 shows an LDAP JAAS realm that uses the properties file in Example 7.8.


The ${ldap.password} placeholder will be replaced with the decrypted value of the ldap.password property from the properties file.

The console provides commands that you can use to perform basic management of your Fuse MQ Enterprise environment, including managing destinations, connections and other administrative objects in the broker.

The console uses prefixes to group commands relating to the same functionality. For example commands related to configuration are prefixed config:, and logging-related commands are prefixed log:.

The console provides two levels of help:

  • console help—list all of the commands along with a brief summary of the commands function

  • command help—a detailed description of a command and its arguments

To access the console help you use the help command from the console prompt. It will display a grouped list of all the commands available in the console. Each command in the list will be followed by a description of the command as shown in Example 8.2.


The help for each command includes the definition, the syntax, and the arguments and any options. To display the help for a command, type the command with the --help option. As shown in Example 8.3, entering admin:start --help displays the help for that command.


How you connect a command console to a broker on a remote machine depends on if the brokers are part of the same fabric. If the remote broker you want to command is a part of the same fabric as the broker whose command console you are using, then you can use the fabric:container-connect command to establish a connection to the remote broker.

The fabric:container-connect command has one required argument that specifies the name of the container to which a connection will be opened. You can also specify a command to be executed by the remote console connection. If you do not specify a command, you are presented with a prompt that will pass commands to the remote broker's console. For more details about fabric:container-connect, see fabric:container-connect, in Console Reference.

If you are not using fabric, or the remote broker is not part of the same fabric as the broker whose command console you are using, you create a remote connection using the ssh:ssh command. The ssh:ssh command also only requires a single argument to establish the remote connection. In this case, it is the hostname, or IP address, of the machine on which the broker is running. If the remote broker is not using the default SSH port (8101), you will also need to specify the remote broker's SSH port using the -p flag. You can also specify a command to be executed by the remote console connection. If you do not specify a command, you are presented with a prompt that will pass commands to the remote broker's console. For more details about ssh:ssh, see ssh:ssh, in Console Reference.

To disconnect from the remote console, you use the logout command or press Control+D.

When deploying multiple brokers, you need to decide how you want to manage the brokers:

  • as a collection of standalone brokers

  • a fabric of brokers

All of the advanced networking features such as fail over, network of brokers, load balancing, and master/slave are available regardless of how you choose to manage your broker deployment. The difference is in what is required to set up and maintain the deployment.

Using a collection of standalone brokers requires that you install, configure, and maintain each broker separately. If you have three brokers, you will need to manually install Fuse MQ Enterprise on three machines and configure each installation separately. This can be cumbersome and error prone particularly when configuring a network of brokers. When issues arise or you need to update your deployment, you will have to make the changes on each machine individually.

If you brokers are deployed into a fabric, you can perform the installation and configuration of all the brokers in the deployment from a central location. In addition, using a fabric simplifies the configuration process and makes it less error prone. Fabric provides tooling for auto-configuring failover clusters, networks of brokers, and master/slave clusters. In addition, it also makes it possible to place all of the common configuration into a single profile that all of the brokers share. When issues arise or you need to update your deployment, having your brokers in a fabric allows you to do incremental roll outs and provides a means for quickly rolling back any changes.

To deploy a new broker into a fabric:

  1. Create a template Fuse MQ Enterprise XML configuration file in a location that is accessible to the container.

  2. In the command console, use the fabric:import command to upload the your XML configuration template to the Fabric Ensemble as shown in Example 9.1.


    version must match the version of the new profile you will create for the new broker.

  3. Use the fabric:mq-create command to create a profile for the new broker and assign it to a container.

    [Tip]Tip

    You can add network configuration settings to the profile as well. See fabric:mq-create in Console Reference.

  4. Use the fabric:profile-edit command shown in Example 9.4 to set the required properties.


    The properties that need to be set will depend on the properties you specified using property place holders in the template XML configuration and the broker's network settings.

    For information on using fabric:profile-edit see fabric:profile-edit in Console Reference.

[Tip]Tip

Fuse Management Console makes this process easier by providing a Web based UI.

[Important]Important

If the broker is running in console mode it can only be shutdown locally.

When Fuse MQ Enterprise is installed it is set up to run a standalone broker. If you want the broker to become part of a fabric you have two options:

  • join an existing fabric

    This option is useful if you have an existing fabric and simply want to add the broker to it. You can add the broker as a fully managed container in which the broker's existing configuration is wiped out and replaced with a profile from the fabric's repository. You can also add the broker as an unmanaged container that retains all of its configuration, but can be discovered through the fabric's ensemble.

    [Tip]Tip

    This option can also be used to move a broker from one fabric to another.

  • create a new fabric

    This option converts the standalone broker into a Fabric Server. You will then need to either add a new broker to the fabric, or assign a broker profile to the server.

Any standalone broker can be joined to an existing fabric using the fabric:join. You need to supply the URL of one of the Fuse Servers in the fabric and the standalone broker is added to the fabric. The broker can join the fabric as either a managed container or a non-managed container:

  • A managed container is a full member of the fabric and is managed by a Fabric Agent. The agent configures the container based on information provided by the fabric's ensemble. The ensemble knows which profiles are associated with the container and the agent determines what to install based on the contents of the profiles.

  • A non-managed container is not managed by a Fabric Agent. It's configuration remains intact after it joins the fabric and is controlled as if the broker were a standalone broker. Joining the fabric in this manner registers the broker with the fabric's ensemble and allows clients to locate the broker using the fabric's discovery mechanism.

Several things happen when a broker joins a fabric as a managed container:

  1. The broker installs the required Fuse Fabric bundles to interact with the fabric's ensemble.

  2. The broker contacts the specified Fabric Server and initiates the joining process.

  3. The Fabric Server registers the container with the fabric's ensemble.

    This adds the container's information to the fabric's registry using the container name as the key. Because the container is a managed container, the registry creates an empty entry for the container and only includes the information it needs to manage the container.

    [Warning]Warning

    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.

  4. The Fabric Server, as a delegate of the fabric's ensemble, takes control of the container.

    This process clears the container and resets its configuration to a default state.

  5. The ensemble installs the fabric profile into the container.

    This loads the Fabric Agent into the container to facilitate the management of the container.

  6. The agent monitors the container and the ensemble for changes.

    If the state of the container changes, the agent updates the ensemble's registry entry. If the ensemble has updates for the container, such as a new profile being associated with the container or a change to one of the profiles already associated with the container, the agent updates the container.

To join a broker to a fabric and have it start up as a broker:

  1. Create a profile for your broker.

    For details on creating a broker profile see Editing a Broker's Configuration in a Fabric.

  2. Get the URL for one of the Fabric Servers in the existing fabric.

    The URL of a Server has the following format:

    HostName:IPPort

    For example, given a fabric registry agent running on the host, myhost, the URL would be myhost:2181. The IP port, 2181, is the default IP port used by a Fabric Server and is usually the correct value to use. If you are in any doubt about which URL to use you can discover the URLs of the Fabric Servers as follows:

    1. Connect to the command console of one of the containers in the fabric.

    2. Enter the following sequence of console commands:

      FuseMQ:karaf@root> config:edit org.fusesource.fabric.zookeeper
      FuseMQ:karaf@root> config:proplist
         service.pid = org.fusesource.fabric.zookeeper
         zookeeper.url = myhostA:2181,myhostB:2181,myhostC:2181,myhostC:2182,myhostC:2183
         fabric.zookeeper.pid = org.fusesource.fabric.zookeeper
      FuseMQ:karaf@root> config:cancel

      The zookeeper.url property holds a comma-separated list of Fabric Server URLs. You can use any one of these URLs to join the fabric.

  3. Connect to the standalone broker's command console.

  4. Enter the following command:

    FuseMQ:karaf@root> fabric:join -p brokerProfile fabricURL brokerName

    You need to provide values for:

    For details on fabric:join see fabric:join in Console Reference.

To join a broker to a fabric a non-managed container:

Fuse MQ 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

By default Fuse MQ Enterprise creates MBeans, loads them into the MBean server created by the JVM, and creates a dedicated JMX connector that provides a Fuse MQ Enterprise-specific view of the MBean server. The default settings are sufficient for simple deployments and make it easy to access the statistics and management operations provided by a broker. For more complex deployments you easily configure many aspects of how a broker configures itself for access through JMX. For example, you can change the JMX URI of the JMX connector created by the broker or force the broker to use the generic JMX connector created by the JVM.

By connecting a JMX aware management and monitoring tool to a broker's JMX connector, you can view detailed information about the broker. This information provides a good indication of broker health and potential problem areas. In addition to the collected statistics, Fuse MQ Enterprise's JMX interface provides a number of operations that make it easy to manage a broker instance. These include stopping a broker, starting and stopping network connectors, and managing destinations.

If the default JMX behavior is not appropriate for your deployment environment, you can customize how the broker exposes its MBeans. To customize a broker's JMX configuration, you add a managementContext child element to the broker's broker element. The managementContext element uses a managementContext child to configure the broker. The attributes of the inner managementContext element specify the broker's JMX configuration.

Table 13.1 describes the configuration properties for controlling a broker's JMX behavior.


Example 13.1 shows configuration for a broker that will only use the JVM's MBean server and will not create its own JMX connector.


Table 13.3 describes the statistics collected for a destination.

Table 13.3. Destination JMX Statistics

NameDescription
BlockedProducerWarningIntervalSpecifies, in milliseconds, the interval between warnings issued when a producer is blocked from adding messages to the destination.
MemoryLimitSpecifies the memory limit, in bytes, used for holding undelivered messages before paging to temporary storage.
MemoryPercentageUsedSpecifies the percentage of available memory in use.
MaxPageSizeSpecifies the maximum number of messages that can be paged into the destination.
CursorFullSpecifies if the cursor has reached its memory limit for paged messages.
CursorMemoryUsageSpecifies, in bytes, the amount of memory the cursor is using.
CursorPercentUsageSpecifies the percentage of the cursor's available memory is in use.
EnqueueCountSpecifies the number of messages that have been sent to the destination.
DequeueCountSpecifies the number of messages that have been acknowledged and removed from the destination.
DispatchCountSpecifies the number of messages that have been delivered to consumers, but not necessarily acknowledged by the consumer.
InFlightCountSpecifies the number of dispatched to, but not acknowledged by, consumers.
ExpiredCountSpecifies the number of messages that have expired in the destination.
ConsumerCountSpecifies the number of consumers that are subscribed to the destination.
QueueSizeSpecifies the number of messages in the destination that are waiting to be consumed.
AverageEnqueueTimeSpecifies the average amount of time, in milliseconds, that messages sat in the destination before being consumed.
MaxEnqueueTimeSpecifies the longest amount of time, in milliseconds, that a message sat in the destination before being consumed.
MinEnqueueTimeSpecifies the shortest amount of time, in milliseconds, that a message sat in the destination before being consumed.
MemoryUsagePortionSpecifies the portion of the broker's memory limit used by the destination.
ProducerCountSpecifies the number of producers connected to the destination.

Table 13.5 describes the operations exposed by the MBean for a broker.

Table 13.5. Broker MBean Operations

OperationDescription
void start(); Starts the broker. In reality this operation is not useful because you cannot access the MBeans if the broker is stopped.
void stop(); Forces a broker to shut down. There is no guarantee that all messages will be properly recorded in the persistent store.
void stopGracefully(String queueName); Checks that all listed queues are empty before shutting down the broker.
void enableStatistics(); Activates the broker's statistics plug-in.
void resetStatistics(); Resets the data collected by the statistics plug-in.
void disableStatistics(); Deactivates the broker's statistics plug-in.
String addConnector(String URI); Adds a transport connector to the broker and starts it listening for incoming client connections and returns the name of the connector.
boolean removeConnector(String connectorName); Deactivates the specified transport connector and removes it from the broker.
String addNetworkConnector(String URI); Adds a network connector to the specified broker and returns the name of the connector.
boolean removeNetworkConnector(String connectorName); Deactivates the specified connector and removes it from the broker.
void addTopic(String name); Adds a topic destination to the broker.
void addQueue(String name); Adds a queue destination to the broker.
void removeTopic(String name); Removes the specified topic destination from the broker.
void removeQueue(String name); Removes the specified queue destination from the broker.
ObjectName createDurableSubscriber(String clientId,
                                   String subscriberId,
                                   String topicName,
                                   String selector);
Creates a new durable subscriber.
void destroyDurableSubscriber(String clientId,
                              String subscriberId);
Destroys a durable subscriber.
void gc(); Runs the JVM garbage cleaner.
void terminateJVM(int exitCode); Shuts down the JVM.
void reloadLog4jProperties(); Reloads the logging configuration from log4j.properties.

Table 13.8 describes the operations exposed by the MBean for a queue destination.

Table 13.8. Queue MBean Operations

OperationDescription
CompositeData getMessage(String messageId); Returns the specified message from the queue without moving the message cursor.
void purge(); Deletes all of the messages from the queue.
boolean removeMessage(String messageId); Deletes the specified message from the queue.
int removeMatchingMessages(String selector); Deletes the messages matching the selector from the queue and returns the number of messages deleted.
int removeMatchingMessages(String selector,
                           int maxMessages);
Deletes up to the maximum number of messages that match the selector and returns the number of messages deleted.
boolean copyMessageTo(String messageId,
                      String destination);
Copies the specified message to a new destination.
int copyMatchingMessagesTo(String selector,
                           String destination);
Copies the messages matching the selector and returns the number of messages copied.
int copyMatchingMessagesTo(String selector,
                           String destination,
                           int maxMessages);
Copies up to the maximum number of messages that match the selector and returns the number of messages copied.
boolean moveMessageTo(String messageId,
                      String destination);
Moves the specified message to a new destination.
int moveMatchingMessagesTo(String selector,
                           String destination);
Moves the messages matching the selector and returns the number of messages moved.
int moveMatchingMessagesTo(String selector,
                           String destination,
                           int maxMessages);
Moves up to the maximum number of messages that match the selector and returns the number of messages moved.
boolean retryMessage(String messageId); Moves the specified message back to its original destination.
int cursorSize(); Returns the number of messages available to be paged in by the cursor.
boolean doesCursorHaveMessagesBuffered(); Returns true if the cursor has buffered messages to be delivered.
boolean doesCursorHaveSpace(); Returns true if the cursor has memory space available.
CompositeData[] browse(); Returns all messages in the queue, without changing the cursor, as an array.
CompositeData[] browse(String selector); Returns all messages in the queue that match the selector, without changing the cursor, as an array.
TabularData browseAsTable(String selector); Returns all messages in the queue that match the selector, without changing the cursor, as a table.
TabularData browseAsTable(); Returns all messages in the queue, without changing the cursor, as a table.
void resetStatistics(); Resets the statistics collected for the queue.
java.util.List browseMessages(String selector); Returns all messages in the queue that match the selector, without changing the cursor, as a list.
java.util.List browseMessages(); Returns all messages in the queue, without changing the cursor, as a list.
String sendTextMessage(String body,
                       String username,
                       String password);
Send a text message to a secure queue.
String sendTextMessage(String body); Send a text message to a queue.

Incremental patching allows you apply targets fixes to a broker without needing to reinstall an updated version of Fuse MQ 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 broker depends on how the broker is deployed:

  • standalone—the broker'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 broker

    Fuse Management Console is the recommended way to patch brokers in a fabric.

Patching a standalone broker directs the broker to load the patch versions of artifacts instead of the non-patch versions. The patch shell provides commands to patches to the broker'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 MQ 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 broker's system folder. When the patch is applied, the broker'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.

[Important]Important

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

To apply a patch to a standalone broker:

  1. Add the patch to the broker's environment using the patch:add command.

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


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

  2. Simulate installing the patch using the patch:simulate command.

    This will generate a log of the changes that will be made to the broker when the patch is installed, but will not make any actual changes to the broker.

    [Tip]Tip

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

  3. Review the simulation log to understand the changes that will be made to the broker.

  4. Apply the patch to the broker using the patch:install command.

    [Tip]Tip

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

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

A

Active, Subscription statistics
activemq.xml, Editing the configuration template
administration client
running, Running the administration client
administration console
port number, Changing the port
securing, Securing the console
url, Accessing the console
Aries
namespaces, Namespaces
placeholder extension, Placeholder extension
authentication, LDAP properties
AverageEnqueueTime, Destination statistics

B

BlockedProducerWarningInterval, Destination statistics
broker
addConnector, Broker actions
addNetworkConnector, Broker actions
addQueue, Broker actions
addTopic, Broker actions
createDurableSubscriber, Broker actions
deploying
fabric container, Procedure
destroyDurableSubscriber, Broker actions
disableStatistics, Broker actions
enableStatistics, Broker actions
gc, Broker actions
reloadLog4jProperties, Broker actions
removeConnector, Broker actions
removeNetworkConnector, Broker actions
removeQueue, Broker actions
removeTopic, Broker actions
resetStatistics, Broker actions
start, Broker actions
stop, Broker actions
stopGracefully, Broker actions
terminateJVM, Broker actions
useJmx, Enabling and disabling
BrokerId, Broker statistics
BrokerName, Broker statistics
BrokerVersion, Broker statistics

C

client, Running the administration client
command console
getting help, Using the broker console
remote access, Connecting a console to a remote broker
config shell, Editing the OSGi properties
config.properties, Overview
configuration
persistent identifier, OSGi PIDs
PID, OSGi PIDs
template, Configuration templates
connection.password, LDAP properties
connection.url, LDAP properties
connection.username, LDAP properties
connector
connectionCount, Connector actions
disableStatistics, Connector actions
enableStatistics, Connector actions
resetStatistics, Connector actions
start, Connector actions
stop, Connector actions
connectorHost, Advanced configuration
connectorPath, Advanced configuration
connectorPort, Advanced configuration
console
config shell, Editing the OSGi properties
console mode
starting, Starting in console mode
stopping, Stopping the broker from console mode
ConsumerCount, Destination statistics
createConnector, Advanced configuration
createMBeanServer, Advanced configuration
CursorFull, Destination statistics
CursorMemoryUsage, Destination statistics
CursorPercentUsage, Destination statistics

D

daemon mode
starting, Starting in daemon mode
stopping, Stopping a broker running in daemon mode
DataDirectory, Broker statistics
deploying
standalone broker, Deploying a Standalone Broker
DequeueCount, Destination statistics
DequeueCounter, Subscription statistics
DispatchCount, Destination statistics
DispatchedCounter, Subscription statistics
DispatchedQueueSize, Subscription statistics

E

embedded console
disabling, Disabling the embedded console
encryptor, Jasypt configuration
EnqueueCount, Destination statistics
EnqueueCounter, Subscription statistics
ExpiredCount, Destination statistics

F

fabric
profiles, Profiles
starting a broker, Starting a broker in a fabric
stopping a broker, Shutting down remote brokers in a fabric
versions, Profiles
fabric shell, Procedure
fabric:container-change-profile, Remaining a message broker
fabric:container-connect, Connecting a console to a remote broker
fabric:container-start, Starting a broker in a fabric
fabric:container-stop, Shutting down remote brokers in a fabric
fabric:container-upgrade, Using the command console
fabric:create, Creating a New Fabric
fabric:join, Joining a Broker to a Fabric
-n, Joining a Fabric as a Non-Managed Container
-p, Joining a Fabric as a Managed Container
fabric:mq-create, Procedure
features:install, Installing the Jasypt features
Fuse HQ, Tools
Fuse Management Console, Tools
fusemq, Starting in console mode

I

InFlightCount, Destination statistics
initial.context.factory, LDAP properties

L

LDAP
authentication, LDAP properties
configuration, LDAP properties
connection.password, LDAP properties
connection.url, LDAP properties
connection.username, LDAP properties
enabling, Enabling LDAP Authentication
initial.context.factory, LDAP properties
properties, LDAP properties
role.base.dn, LDAP properties
role.filter, LDAP properties
role.name.attribute, LDAP properties
role.search.subtree, LDAP properties
ssl, LDAP properties
ssl.algorithm, LDAP properties
ssl.keyalias, LDAP properties
ssl.keystore, LDAP properties
ssl.protocol, LDAP properties
ssl.provider, LDAP properties
ssl.truststore, LDAP properties
user.base.dn, LDAP properties
user.filter, LDAP properties
user.search.subtree, LDAP properties
LDAPLoginModule, Enabling LDAP Authentication
logging
console commands, Viewing the log with the console, Viewing the log with the administration client
viewing as text, Viewing the log in a text editor
viewing in an editor, Viewing the log in a text editor
viewing in the console, Viewing the log with the console
viewing with the admin client, Viewing the log with the administration client

M

managed container, Joining a Fabric as a Managed Container
managementContext, Advanced configuration
connectorHost, Advanced configuration
connectorPath, Advanced configuration
connectorPort, Advanced configuration
createConnector, Advanced configuration
createMBeanServer, Advanced configuration
jmxDomainName, Advanced configuration
rmiServerPort, Advanced configuration
useMBeanServer, Advanced configuration
MaxEnqueueTime, Destination statistics
MaximumPendingMessageLimit, Subscription statistics
MaxPageSize, Destination statistics
MemoryLimit, Broker statistics, Destination statistics
MemoryPercentageUsed, Broker statistics, Destination statistics
MemoryUsagePortion, Destination statistics
MessageCountAwaitingAcknowledge, Subscription statistics
MinEnqueueTime, Destination statistics
mq-create, Procedure

N

namespaces
Aries, Namespaces
Jasypt, Namespaces
network connector
start, Network connector actions
stop, Network connector actions
non-managed container, Joining a Fabric as a Non-Managed Container

O

org.apache.karaf.log, Overview
org.ops4j.pax.logging, Overview
org.ops4j.pax.logging.DefaultServiceLog.level, Overview
osgi:shutdown, Using a remote console

P

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
patching
fabric
command console, Using the command console
Fuse Management Console, Using Fuse Management Console
standalone, Applying a patch
rollback, Rolling back a patch
PendingQueueSize, Subscription statistics
persistent identifier, OSGi PIDs
PID, OSGi PIDs
PrefetchSize, Subscription statistics
ProducerCount, Destination statistics
profile
creating, Procedure
properties
Apache Karaf placeholder extension, Jasypt configuration
Aries placeholder extension, Placeholder extension
encrypted, Encrypted properties
LDAP, LDAP properties
placeholder, Placeholders
property-placeholder, Placeholder extension, Jasypt configuration

Q

queue
browse, Queue actions
browseAsTable, Queue actions
browseMessages, Queue actions
copyMatchingMessagesTo, Queue actions
copyMessageTo, Queue actions
cursorSize, Queue actions
doesCursorHaveMessagesBuffered, Queue actions
doesCursorHaveSpace, Queue actions
getMessage, Queue actions
moveMatchingMessagesTo, Queue actions
moveMessageTo, Queue actions
purge, Queue actions
removeMatchingMessages, Queue actions
removeMessage, Queue actions
resetStatistics, Queue actions
retryMessage, Queue actions
sendTextMessage, Queue actions
QueueSize, Destination statistics

R

remote console
roles, Changing the remote console's role
rmiServerPort, Advanced configuration
role.base.dn, LDAP properties
role.filter, LDAP properties
role.name.attribute, LDAP properties
role.search.subtree, LDAP properties
roles
default, Default role
JMX, Changing the JMX role, Securing access to JMX
LDAP configuration, LDAP properties
remote console, Changing the remote console's role
routine tasks, Routine tasks
routing console
securing, Securing the console

S

service wrapper
classpath, Adding classpath entries
JMX configuration, JMX configuration
JVM properties, Passing parameters to the JVM
logging, Configuring logging
shell, Starting a basic console
shutdown, Stopping the broker from console mode
ssh:ssh, Connecting a console to a remote broker, Using a remote console
ssl, LDAP properties
ssl.algorithm, LDAP properties
ssl.keyalias, LDAP properties
ssl.keystore, LDAP properties
ssl.protocol, LDAP properties
ssl.provider, LDAP properties
ssl.truststore, LDAP properties
SslSelectChannelConnector, Enabling SSL security
standalone broker
configuration template, Editing the configuration template
deploying, Deploying a Standalone Broker
runtime configuration, Editing the OSGi properties
start, Starting in daemon mode
stop, Stopping a broker running in daemon mode
StoreLimit, Broker statistics
StorePercentageUsed, Broker statistics
subscription
browse, Subscription actions
browseAsTable, Subscription actions
cursorSize, Subscription actions
destory, Subscription actions
doesCursorHaveMessagesBuffered, Subscription actions
doesCursorHaveSpace, Subscription actions
isMatchingQueue, Subscription actions
isMatchingTopic, Subscription actions
system service
Redhat, Redhat Linux
Ubuntu, Ubuntu Linux
Windows, Windows

T

TempLimit, Broker statistics
TempPercentageUsed, Broker statistics
tooling, Tools
topic
browse, Topic actions
browseAsTable, Topic actions
browseMessages, Topic actions
resetStatistics, Topic actions
sendTextMessage, Topic actions
TotalConsumerCount, Broker statistics
TotalDequeueCount, Broker statistics
TotalEnqueueCount, Broker statistics
TotalMessageCount, Broker statistics
TotalProducerCount, Broker statistics

U

useJmx, Enabling and disabling
useMBeanServer, Advanced configuration
user.base.dn, LDAP properties
user.filter, LDAP properties
user.search.subtree, LDAP properties

V

VisualVM, Tools

W

Web console
accessing, Accessing the console
basic authentication, Enabling basic authentication
clusters, Monitoring clusters
port number, Changing the port
roles, Editing user credentials
securing, Securing the console
SSL, Enabling SSL security
user credentials, Editing user credentials
webconsole.jms.url, Configuring Tomcat, Monitoring clusters
webconsole.jmx.password, Configuring Tomcat
webconsole.jmx.url, Configuring Tomcat, Monitoring clusters
webconsole.jmx.user, Configuring Tomcat