Version 7.1
Copyright © 2012 Red Hat, Inc. and/or its affiliates.
Updated: 07 Jan 2014
Table of Contents
List of Figures
List of Tables
List of Examples
Once a messaging solution is deployed it needs to be monitored to ensure it performs at peak performance. When problems do arise, many of them can be solved using the broker's administrative tools. The broker's administrative tools can also be used to provide important debugging information when troubleshooting problems.
Message brokers are long lived and usually form the backbone of the applications of which they are a part. Over the course of a broker's life span, there are a number of management tasks that you may need to do to keep the broker running at peak performance. This includes monitoring the health of the broker, adding destinations, and security certificates.
If applications run into trouble one of the first places to look for clues is the broker. The broker is unlikely to be the root cause of the problem, but its logs and metrics will provide clues as to what is the root cause. You may also be able to resolve the problem using the broker's administrative interface.
While Fuse MQ Enterprise is designed to require a light touch for management, there are a few routine management tasks that need to be performed:
installing SSL certificates
starting the broker
creating destinations
stopping the broker
maintaining the advisory topics
monitoring the health of the broker
monitoring the health of the destinations
If an application runs into issues the broker will usually be able to provide clues to what is going wrong. Because the broker is central to the operation of any application that relies on messaging, it will be able to provide clues even if the broker is functioning properly. You may also be able to solve the problem by making adjustments to the broker's configuration.
Common things to check for clues as to the nature of a problem include:
the broker's log file
the advisory topics
the broker's overall memory footprint
the size of individual destination
the total number of messages in the broker
the size of the broker's persistent store
a thread dump of the broker
One or more of these items can provide information about the problem. For example, if a destination grows to a very large size it could indicate that one of its consumers is having trouble keeping up with the messages. If the broker's log also shows that the consumer is repeatedly connecting and disconnecting from the destination, that could indicate a networking problem or a problem with the machine hosting the consumer.
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
Fuse MQ Enterprise configuration uses a combination of an XML configuration template and OSGi PID configuration. This combination makes it possible to change specified broker properties on the fly. How you change the configuration depends on how the broker instance is deployed.
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 |
|---|---|
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. |
One of the weaknesses of the Apache ActiveMQ configuration model is that any changes require a broker restart. Fuse MQ Enterprise addresses this weakness by capitalizing on the OSGi Admin service. The container combines both the Apache ActiveMQ XML configuration and OSGi persistent identifier(PID) properties to manage a broker instances runtime configuration.
In Fuse MQ Enterprise your Apache ActiveMQ XML configuration file becomes a configuration template. It can contain property placeholders for any settings that may need to be set on the fly. It can also be used as a baseline for configuring a group of brokers and the placeholders represent settings that need to be modified for individual brokers.
As shown in Figure 2.1, the configuration template is combined with the OSGi PID properties. While the broker is running the OSGi Admin service monitors the appropriate PIDs for changes. When it detects a change, the admin service will automatically change the broker's runtime configuration.
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
${ 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.propName}
Example 2.1. Adding Property Placeholder Support to Fuse MQ Enterprise Configuration
<!-- Allows us to use system properties and fabric as variables in this configuration file --> <bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"> <property name="properties"> <bean class="org.fusesource.mq.fabric.ConfigurationProperties"/> </property> </bean> <broker ... > ... </broker>
The configuration template shown in Example 2.2 uses three property placeholders that allow you to modify the base configuration using fabric properties.
Example 2.2. Configuration with Property Placeholders
<broker xmlns="http://activemq.apache.org/schema/core" brokerName="${broker-name}" dataDirectory="${data}" persistent="${persists}" start="false"> ... <persistenceAdapter> <jdbcPersistenceAdapter dataDirectory="${data}/derby" dataSource="#derby-ds" /> </persistenceAdapter> </broker>
Persistent identifiers are described in chapter 104,
[Configuration Admin Service Specification], of the
[OSGi Compendium Services Specification]. It is a unique key used by the
OSGi framework's admin service to associate configuration properties with active services.
The PIDs for a Fuse MQ Enterprise instance have the prefix
org.fusesource.mq.fabric.server.
Every PID has a physical representation as a file of name value pairs. For standalone
brokers the files are located in the etc/ folder and use the
.cfg extension and are updated using the
config shell. For broker's in a fabric the files are stored in the Fabric
Ensemble and are edited using the fabric shell's profile management
commands.
A standalone broker is one that is not part of a fabric. A standalone broker can, however, be part of a network of broker, a master/slave cluster, or a failover cluster. The distinction is that a standalone is responsible for managing and storing its own configuration.
All of the configuration changes are made directly on the local instance. You make changes using a combination of edits to local configuration template and commands from the console's config shell. The configuration template must be edited using an external editor. The configuration the control's the behavior of the broker's runtime container is changed using the console commands.
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 initial values for all of the OSGi properties configuring the broker are specified in the
etc/org.fusesource.mq.fabric.server-default.cfg file. You can edit these
values using the command console's config shell. The PID for these values are
org.fusesource.mq.fabric.server.. The
idid is assigned by the container when the broker is started.
In addition to the broker's messaging behavior, a number of the broker's runtime behavior such as logging levels, the Web console behavior, and the JMX behavior are controlled by by OSGi properties stored in different PIDs.
To find the value for a broker's id use and the PIDs for the
other runtime configuration settings, use the config:list command.
The config shell has a series of commands for editing OSGi properties:
config:list—lists all of the runtime configuration files and the current values for their properties
config:edit—opens an editing session for a configuration file
config:propset—changes the value of a configuration property
config:propdel—deletes a configuration property
config:update—saves the changes to the configuration file being edited
For more information about the config shell commands, see Config Console Commands in Console Reference.
When a broker is part of a fabric, it does not manage its configuration. The broker's configuration is managed by the Fabric Agent. The agent runs along with the broker and updates the broker's configuration based on information from the fabric's registry.
Because the configuration is managed by the Fabric Agent, any changes to the broker's configuration needs to be done by updating the fabric's registry. In a fabric, broker configuration is determined by one or more profiles that are deployed into the broker. To change a broker's configuration, you must update the profile(s) deployed into the broker using either the console's fabric: shell or Fuse Management Console.
All configuration in a fabric is stored as profiles in the Fabric Registry. One or more profiles are assigned to brokers that are part of the fabric. A profile is a collection of configuration that specifies:
the Apache Karaf features to be deployed
OSGi bundles to be deployed
the repositories from which artifacts can be provisioned
properties that configure the broker's runtime behavior
The configuration profiles are collected into versions. Versions are typically used to make updates to an existing profile without effecting deployed brokers. When a container is configured it is assigned a profile version from which it draws the profiles. Therefore, when you create a new version and edit the profiles in the new version, the profiles that are in use are not changed. When you are ready to test the changes, you can roll them out incrementally by moving brokers to a new version one at a time.
When a broker joins a fabric, a Fabric Agent is deployed with the broker and takes control of the broker's configuration. The agent will ask the Fabric Registry what version and profile(s) are assigned to the broker and configure the broker based on the profiles. The agent will download and install of the specified bundles and features. It will also set all of the specified configuration properties.
The recommended approach to configuring brokers in a fabric is:
Create a configuration template.
Create a base profile for all of the brokers in the fabric using the configuration template.
Create profiles that inherit from the base profile that will be assigned to one or more brokers.
Modify the properties in each of the profiles to the desired values for the brokers to which the profile will be assigned.
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.
To create a base profile:
Optionally create a new profile version using the fabric:version-create command.
This will create a new copy of the existing profiles. See fabric:version-create in Console Reference for more information.
Import the new XML template into the registry using the fabric:import command as shown in Example 2.4.
Example 2.3. Importing an XML Configuration Template
FuseMQ:karaf@root>fabric:import -t /fabric/configs/versions/version/profiles/mq-base/xmlTemplatexmlTemplatePath
See fabric:import in Console Reference for more information.
Create a new configuration profile instance to hold the new XML template using the fabric:mq-create command as shown in Example 2.4.
Example 2.4. Creating a Profile Using an XML Configuration Template
FuseMQ:karaf@root>fabric:mq-create --configxmlTemplateprofileName
This will create a new profile that is based on the default broker profile but uses the imported XML template. See fabric:mq-create in Console Reference for more information.
To create deployment profiles and assigned them to the brokers:
Create new profile using the fabric:profile-create command as shown in Example 2.5.
Example 2.5. Creating a Deployment Profile
FuseMQ:karaf@root>fabric:profile-create --parentsbaseProfileprofileName
This will create a new profile that inherits from the base profile. See fabric:profile-create in Console Reference for more information.
Add values for the property placeholders using the fabric:profile-edit command as shown in Example 2.6.
Example 2.6. Setting Properties in a Profile
FuseMQ:karaf@root>fabric:profile-edit -p org.fusesource.mq.fabric.server-profileName/propName=propValprofileName
The fabric properties for a broker are specified using the PID
org.fusesource.mq.fabric.server-, so
to specify a value for the broker-name property for the profile
called profileNamemyBroker you would use the command shown in
Example 2.7.
Example 2.7. Setting the Broker Name Property
FuseMQ:karaf@root>fabric:profile-edit -p org.fusesource.mq.fabric.server-myBroker/broker-name=esmeralda myBroker
Assign the new profile to one or more brokers using the fabric:container-add-profile command as shown in Example 2.8.
Example 2.8. Assigning a Profile to a Broker
FuseMQ:karaf@root>fabric:container-add-profilebrokerNameprofileName
See fabric:container-add-profile, in Console Reference for more information.
Fuse Management Console simplifies the process of configuring brokers in a fabric by providing an easy to use Web-based interface and reducing the number of steps required to make the changes. For more information on using Fuse Management Console see the Fuse Management Console Documentation.
The Fuse MQ Enterprise runtime exposes three ports for remote access. These ports, which are mostly intended for managing the broker, are essentially disabled by default. They are configured to require authentication, but have no defined users. This makes the broker immune to breaches, but is not ideal for remote management.
Figure 3.1 shows the ports exposed by the Fuse MQ Enterprise container by default.
The following ports are exposed by the container:
Console port—enables remote control of a container instance, through Apache Karaf shell commands. This port is enabled by default and is secured both by JAAS authentication and by SSL.
JMX port—enables management of the container through the JMX protocol. This port is enabled by default and is secured by JAAS authentication.
Web console port—provides access to an embedded Jetty container that can host Web console servlet.
Fuse MQ Enterprise uses Java Authentication and Authorization Service (JAAS) for ensuring the users trying to access the broker have the proper credentials. The implementation is modular, with individual JAAS modules providing the authentication implementations. Fuse MQ Enterprise's command console provides commands to configure the JAAS system.
The default security settings block access to a broker's remote ports. If you want to access the Fuse MQ Enterprise runtime remotely, you must first customize the security configuration. The first thing you will want to do is create at least one JAAS user. This will enable remote access to the broker.
Other common configuration changes you may want to make are:
configure access to the Web console
assign roles to each of the remote ports to limit access
strengthen the credentials needed to access the remote console
By default, no JAAS users are defined for the container, which effectively disables remote access (it is impossible to log on).
To create a secure JAAS user, edit the
file and add a new
user field, as follows:InstallDir/etc/users.properties
Username=Password,admin
Where and
Username are the new user credentials. The
Passwordadmin role gives this user the privileges to access all administration and
management functions of the container. For more details about JAAS, see
JAAS Authentication in Security Guide.
![]() | Warning |
|---|---|
It is strongly recommended that you define custom user credentials with a strong password. |
If you want to access the Web console (for remote administration of JMS messaging), you must provide the Web console servlet with the credentials it needs to login to the JMS broker.
Edit the file
and modify the InstallDir/etc/system.propertieswebconsole.jmx.* and webconsole.jms.* properties as
follows:
webconsole.jmx.user=Usernamewebconsole.jmx.password=Passwordwebconsole.jms.user=Usernamewebconsole.jms.password=Password
Where the and
Username are the credentials of a JAAS user with
Passwordadmin privileges.
For more details on securing the Web console see Securing the Web Console.
You can independently configure roles for the following different administrative protocols:
SSH (remote console login)
To override the default role for the remote console add a sshRole
property to the org.apache.karaf.shell PID. The following
sets the role to admin:
sshRole=admin
JMX management
To override the default role for JMX add a jmxRole
property to the org.apache.karaf.management PID. The
following sets the role to jmx:
jmxRole=jmx
Web console
You can employ the following measures to strengthen security on the remote console port:
Make sure that the JAAS user credentials have strong passwords.
Customize the X.509 certificate (replace the Java keystore file,
, with a custom key
pair).InstallDir/etc/host.key
For more details, see Securing the Fuse MQ Enterprise Container.
Prior to Fuse MQ Enterprise version 7.0.2, the Apache ActiveMQ broker was insecure (JAAS authentication not enabled). This section explains how to revert the Apache ActiveMQ broker to an insecure mode of operation, so that it is unnecessary to provide credentials when connecting to the broker.
![]() | Warning |
|---|---|
After performing the steps outlined in this section, the broker has no protection against hostile clients. This type of configuration is suitable only for use on internal, trusted networks. |
These instructions assume that you are running Fuse MQ Enterprise in standalone mode (that is,
running in an OSGi container, but not using Fuse Fabric). In your installation of Fuse MQ Enterprise,
open the file using a
text editor and look for the following lines:InstallDir/etc/activemq.xml
...
<plugins>
<jaasAuthenticationPlugin configuration="karaf" />
</plugins>
...To disable JAAS authentication, delete (or comment out) the
jaasAuthenticationPlugin element. The next time you start up the Fuse MQ Enterprise
container (using the script),
the broker will run with unsecured ports.InstallDir/bin/fusemq
Fuse MQ Enterprise's Web console is an easy way to query a standalone broker for JMX statistics, destination statuses, and information on any routes deployed in the broker.
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 |
|---|---|
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 |
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 |
|---|---|
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 |
The default port and security configuration can easily be modified.
The Fuse MQ Enterprise Web console's address is
http://
.hostName:portNum/activemqweb
For example, to access the default broker administration console on your local machine, you would
point your Web browser at
http://localhost:8181/activemqweb
.
The port number at which the Web console is accessed is controlled by the broker's Pax
Web server. To change the port, you need to edit the
org.osgi.service.http.port property in the
org.ops4j.pax.web OSGi Admin PID.
Example 4.1 shows the console commands used to change
the port number of a standalone broker's Web console to 8536.
Example 4.1. Changing the Web Console's Port
FuseMQ:karaf@root>config:edit org.ops4j.pax.webFuseMQ:karaf@root>config:proplistservice.pid = org.ops4j.pax.web javax.servlet.context.tempdir = /Applications/FuseMQEnterprise-7.0.0/fuse-mq-7.0.0.fuse-beta-042/data/pax-web-jsp org.osgi.service.http.port = 8181 org.ops4j.pax.web.config.file = /Applications/FuseMQEnterprise-7.0.0/fuse-mq-7.0.0.fuse-beta-042/etc/jetty.xml org.apache.karaf.features.configKey = org.ops4j.pax.webFuseMQ:karaf@root>config:propset org.osgi.service.http.port 8536FuseMQ:karaf@root>config:update
The security for the Web console is provided by the Web container in which it is
deployed. For the embedded instance of the Web console, you need to configure the
embedded Jetty container's security by editing conf/jetty.xml.
See Securing the Web Console for details.
By default the Fuse MQ Enterprise Web console is insecure. It does not require authentication and
uses the standard HTTP transport. For most commercial deployments, it is advisable that
the Web console is secured. Adding security is done by editing the
etc/jetty.xml configuration file.
The Jetty server can be configured to enable HTTP basic authentication. Although the
conf/jetty.xml file already includes most of the configuration required
for basic authentication, the authentication feature is disabled by default. To enable it,
search for the following line in the jetty.xml file:
<property name="authenticate" value="false" />
Edit the value attribute, changing its value to
true. The result should be similar to:
<property name="authenticate" value="true" />
When you restart the broker, basic authentication will be enabled on the Web console.
For example, you can log on using the credentials, username=admin,
password=admin.
The Jetty user data are stored in the conf/jetty-realm.properties
file, which you can edit to add user credentials and roles. Each user is defined on a
separate line, which has the following format:
Username:Password[,Role01,Role02, ...]
For example, to define the user with username, jblogs, password,
secret, and role, developer, you would add the following line to
the jetty-realm.properties file:
jblogs: secret, developer
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.
Example 4.2. SSL Enabled Web Console Configuration
<property name="connectors"> <list> <bean id="Connector" class="org.eclipse.jetty.server.ssl.SslSelectChannelConnector"> <property name="port" value="8443" /> <property name="maxIdleTime" value="30000"/> <property name="keystore" value="${activemq.home}/conf/broker.ks"/> <property name="password" value="testjetty"/> <property name="keyPassword" value="testjetty"/> <property name="truststore" value="${activemq.home}/conf/broker.ks"/> </bean> </list> </property>
The SslSelectChannelConnector properties can be explained as
follows:
port—specifies the secure IP port number (accessible
through HTTPS).
maxIdleTime—specifies the connection idle time in milliseconds.
If there is no activity on a connection for longer than this timeout, the connection
will be closed.
keystore—specifies the location of the Jetty server's X.509
certificate, which is stored in a Java keystore file on the file system. The Jetty
server uses this certificate to identify itself to a client, during the SSL
handshake.
password—specifies the store password,
which is needed to unlock the keystore file. See
Java Keystores in Security Guide.
keyPassword—specifies the key password,
which is used to decrypt the private key that is stored within the keystore file.
Typically, the store password and the key password are identical. Some SSL
implementations even require this to be the case.
truststore—specifies the location of a Java keystore file that
contains a list of one or more trusted certificates, which can be used during the SSL
handshake to check that incoming client certificates are correctly signed.
![]() | Note |
|---|---|
In the current example, the truststore is actually irrelevant, because clients are not required to send a certificate to the Jetty server. |
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 |
|---|---|
The |
For more details about the properties you can set on the
SslSelectChannelConnector class, see
http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/server/ssl/SslSocketConnector.html.
For more security or reliability reasons you can deploy the Web console as a standalone application in Tomcat or another Web container. When running as a standalone application, the Web console can be set up to monitor Master/Slave clusters.
There is no need to disable the embedded console when using a standalone console. However, If you are using a standalone Web console, there is no reason to use the resources required by the embedded console. Nor is there a reason to leave an extra administrative access point open.
To disable the embedded Web console, you simply need to comment out, or remove, the
import element that imports the Jetty configuration into your
broker's configuration file as shown in
Example 4.3.
Example 4.3. Disabling the Embedded Web Console
<beans ... > <broker ... > ... </broker> <!-- <import resource="jetty.xml"/> --> </beans>
To deploy the Web console in Tomcat 5.x:
Download the Web console's WAR,
activemq-web-console-7.1.0.fuse-047.war, from
http://repo.fusesource.com/nexus/content/repositories/releases/org/apache/activemq/activemq-web-console/5.7.0.fuse-71-047/.
Copy the Web console's WAR to the
folder.TOMCAT_HOME/webapps
Download activemq-all-7.1.0.fuse-047.jar from
http://repo.fusesource.com/nexus/content/repositories/releases/org/apache/activemq/activemq-all/5.7.0.fuse-71-047/.
Copy activemq-all-7.1.0.fuse-047.jar to the
folder.TOMCAT_HOME/common/lib
Modify
to
include the configuration in Example 4.4.TOMCAT_HOME/bin/catalina.sh(.bat)
Example 4.4. Configuration for Deploying the Web Console in Tomcat
JAVA_OPTS="-Dwebconsole.type=properties \ -Dwebconsole.jms.url=brokerURL\ -Dwebconsole.jmx.url=brokerJMXURL\ -Dwebconsole.jmx.user=JMXUserName\ -Dwebconsole.jmx.password=JMXPassword"
Restart Tomcat.
The Web console will be available at
.tomcatURI/activemq-web-console-5.7.0.fuse-71-047
It's possible to configure the Web console to monitor a master/slave cluster. To do so:
Specify the JMS URL, webconsole.jms.url, with a failover:
URI specifying the brokers in the cluster.
Specify the JMX URL, webconsole.jmx.url as a comma separated list
that contains the JMX URL for each of the brokers in the cluster.
Example 4.5 shows the properties for monitoring a cluster using the Web console.
Example 4.5. Configuration for Monitoring a Cluster with the Web Console
-Dwebconsole.jms.url=failover:(tcp://serverA:61616,tcp://serverB:61616) -Dwebconsole.jmx.url=service:jmx:rmi:///jndi/rmi://serverA:1099/jmxrmi,service:jmx:rmi:///jndi/rmi://serverB:1099/jmxrmi
For more information about master/slave clusters see Master/Slave in Fault Tolerant Messaging.
The Fuse MQ Enterprise installer generates a service wrapper that can be easily configured to install Fuse MQ Enterprise as a system service.
Installing Fuse MQ Enterprise as a system service is a two step process:
The service wrapper is configured by the
file, which is
located under the ServiceName-wrapper.conf
directory.InstallDir/etc/
There are several settings you may want to change including:
the default environment settings
the properties passed to the JVM
the classpath
the JMX settings
the logging settings
A broker's environment is controlled by three environment variables:
KARAF_HOME—the location of the Fuse MQ Enterprise install
directory.
KARAF_BASE—the root directory containing the configuration and OSGi
data specific to the broker instance.
The configuration for the broker instance is stored in the
directory. Other data relating to the OSGi runtime is also stored beneath the
base directory.KARAF_BASE/conf
KARAF_DATA—the directory containing the logging and persistence
data for the broker.
Example 5.1 shows the default values.
Example 5.1. Default Environment Settings
set.default.KARAF_HOME=InstallDirset.default.KARAF_BASE=InstallDirset.default.KARAF_DATA=InstallDir\data
If you want to pass parameters to the JVM, you do so by setting wrapper properties using
the form wrapper.java.additional..
<n><n> is a sequence number that must be distinct for each
parameter.
One of the most useful things you can do by passing additional parameters to the JVM
is to set Java system properties. The syntax for setting a Java system property is
wrapper.java.additional..<n>=-DPropName=PropValue
Example 5.2 shows the default Java properties.
Example 5.2. Default Java System Properties
# JVM # note that n is the parameter number starting from 1. wrapper.java.additional.1=-Dkaraf.home="%KARAF_HOME%" wrapper.java.additional.2=-Dkaraf.base="%KARAF_BASE%" wrapper.java.additional.3=-Dkaraf.data="%KARAF_DATA%" wrapper.java.additional.4=-Dcom.sun.managment.jmxremote wrapper.java.additional.5=-Dkaraf.startLocalConsole=false wrapper.java.additional.6=-Dkaraf.startRemoteShell=true wrapper.java.additional.7=-Djava.endorsed.dirs="%JAVA_HOME%/jre/lib/endorsed;%JAVA_HOME%/lib/endorsed;%KARAF_HOME%/lib/endorsed" wrapper.java.additional.8=-Djava.ext.dirs="%JAVA_HOME%/jre/lib/ext;%JAVA_HOME%/lib/ext;%KARAF_HOME%/lib/ext"
You add classpath entries using the syntax
wrapper.java.classpath..
<n><n> is a sequence number that must be distinct for each
classpath entry.
Example 5.3 shows the default classpath entries.
Example 5.3. Default Wrapper Classpath
wrapper.java.classpath.1=%KARAF_BASE%/lib/karaf-wrapper.jar wrapper.java.classpath.2=%KARAF_HOME%/lib/karaf.jar wrapper.java.classpath.3=%KARAF_HOME%/lib/karaf-jaas-boot.jar wrapper.java.classpath.4=%KARAF_BASE%/lib/karaf-wrapper-main.jar
The default service wrapper configuration does not enable JMX. It does, however, include template properties for enabling JMX. To enable JMX:
Locate the line # Uncomment to enable jmx.
There are three properties, shown in Example 5.4, that are used to configure JMX.
Example 5.4. Wrapper JMX Properties
# Uncomment to enable jmx #wrapper.java.additional.n=-Dcom.sun.management.jmxremote.port=1616 #wrapper.java.additional.n=-Dcom.sun.management.jmxremote.authenticate=false #wrapper.java.additional.n=-Dcom.sun.management.jmxremote.ssl=false
Remove the # from in front of each of the properties.
Replace the n in each property to a number that fits into the sequence
of addition properties established in the configuration.
You can change the settings to use a different port or secure the JMX connection.
For more information about using JMX see Using JMX.
The wrapper's logging in configured using the properties described in Table 5.1.
Table 5.1. Wrapper Logging Properties
| Property | Description |
|---|---|
wrapper.console.format |
Specifies how the logging information sent to the console is formated. The format consists of the following tokens:
|
wrapper.console.loglevel | Specifies the logging level displayed on the console. |
wrapper.logfile | Specifies the file used to store the log. |
wrapper.logfile.format | Specifies how the logging information sent to the log file is formated. |
wrapper.console.loglevel | Specifies the logging level sent to the log file. |
wrapper.console.maxsize | Specifies the maximum size, in bytes, that the log file can grow to before the log is archived. The default value of 0 disables log rolling. |
wrapper.console.maxfiles | Specifies the maximum number of archived log files which will be allowed before old files are deleted. The default value of 0 implies no limit. |
wrapper.syslog.loglevel | Specifies the logging level for the sys/event log output. |
For more information about Fuse MQ Enterprise logging see Using Logging.
The operating system determines the exact steps using to complete the installation of Fuse MQ Enterprise as a service. The wrapper:install command provides basic instructions for your operating system.
To install the service run
.
If you used the default start setting, the service will start when Windows is
launched. If you specified InstallDir\bin\ServiceName-service.bat installDEMAND_START, you will need to start the service
manually.
To start the service manually run
net start ". You can also use
the Windows service UI.ServiceName"
To manually stop the service run
net stop " You can also use
the Windows service UI.ServiceName"
You remove the installed the service by running
.InstallDir\bin\ServiceName-service.bat remove
To install the service and configure it to start when the machine boots, run the following commands:
#ln -sInstallDir\bin\ServiceName-service /etc/init.d/#chkconfigServiceName-service --add#chkconfigServiceName-service on
To start the service manually run
service .ServiceName-service start
To manually stop the service run
service .ServiceName-service stop
You remove the installed the service by running the following commands:
#serviceServiceName-service stop#chkconfigServiceName-service --del#rm /etc/init.d/ServiceName-service
To install the service and configure it to start when the machine boots, run the following commands:
#ln -sInstallDir\bin\ServiceName-service /etc/init.d/#update-rc.dServiceName-service defaults
To start the service manually run
/etc/init.d/.ServiceName-service start
To manually stop the service run
/etc/init.d/.ServiceName-service stop
You remove the installed the service by running the following commands:
#/etc/init.d/ServiceName-service stop#rm /etc/init.d/ServiceName-service
A broker can be run in one of two modes:
console mode—the broker starts up as a foreground process and presents the user with a command shell
daemon mode—the broker starts up as a background process that can be manged using a remote console or the provided command line tools
The default location for the broker's configuration for the broker is the
configuration
file. The configuration uses values loaded from the
InstallDir/etc/activemq.xml file
and the
InstallDir/etc/system.properties file.InstallDir/etc/org.fusesource.mq.fabric.server-default.cfg
When you start the broker in console mode you will be placed into a command shell that provides access to a number of commands for managing the broker and its OSGi runtime.
![]() | Important |
|---|---|
When the broker is started in console mode, you cannot close the console without killing the broker. |
To launch a broker in console mode, change to
InstallDir and run one of the commands in
Table 6.1.
If the server starts up correctly you should see something similar to Example 6.1 on the console.
Example 6.1. Broker Console
______ ___ ___ _____ | ___| | \/ || _ | | |_ _ _ ___ ___ | . . || | | | | _|| | | |/ __| / _ \ | |\/| || | | | | | | |_| |\__ \| __/ | | | |\ \/' / \_| \__,_||___/ \___| \_| |_/ \_/\_\ Fuse MQ (7.0.0.fuse-036) http://fusesource.org/mq/ Hit '<tab>' for a list of available commands and '[cmd] --help' for help on a specific command. Hit '<ctrl-d>' or 'osgi:shutdown' to shutdown Fuse MQ.FuseMQ:karaf@root>
Launching a broker in daemon mode runs Fuse MQ Enterprise in the background without a console.
To launch a broker in daemon mode, change to InstallDir and run
one of the commands in Table 6.2.
If a broker is deployed as part of a fabric you can start it remotely in one of three ways:
using the console of one of the other broker's in the fabric
If one of the brokers in the fabric is running in console mode you an use the
fabric:container-start command to start any of the other brokers
in the fabric. The command requires that you supply the container name used when creating
the broker in the fabric. For example to start a broker named fabric-broker3
you woul duse the command shown in Example 6.2.
For more information see fabric:container-start, in Console Reference.
using the administration client of one of the broker's in the fabric
If none of the brokers are running in console mode, you can use the administration client
on one of the brokers to execute the fabric:container-start
command. The administration client is run using the client command
in Fuse MQ Enterprise's bin folder. Example 6.3
shows how to use the remote client to start remote broker in the fabric.
Example 6.3. Starting a Broker in a Fabric with the Administration Client
bin/client fabric:container-start fabric-broker3using Fuse Management Console
Fuse Management Console can start and stop any of the brokers in the fabric it manages from a Web based console.
For more information see the Fuse Management Console Documentation.
The Fuse MQ Enterprise container is secured using JAAS. By defining JAAS realms, you can configure the mechanism used to retrieve user credentials. You can also refine access to the container's administrative interfaces by changing the default roles.
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 jaas:config element is defined in the
http://karaf.apache.org/xmlns/jaas/v1.0.0 namespace. When
defining a JAAS realm you will need to include the line shown in
Example 7.1.
The syntax for the jaas:config element is shown in
Example 7.2.
Example 7.2. Defining a JAAS Realm in Blueprint XML
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.0.0"> <jaas:config name="JaasRealmName" [rank="IntegerRank"]> <jaas:module className="LoginModuleClassName" [flags="[required|requisite|sufficient|optional]"]>Property=Value... </jaas:module> ... <!-- Can optionally define multiple modules --> ... </jaas:config> </blueprint>
The elements are used as follows:
jaas:configDefines 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:moduleDefines a JAAS login module in the current realm.
jaas:module has the following attributes:
className—the fully-qualified class name
of a JAAS login module. The specified class must be available from the bundle
classloader.
flags—determines what happens upon
success or failure of the login operation.
Table 7.1 describes the valid values.
Table 7.1. Flags for Defining a JAAS Module
| Value | Description |
|---|---|
required | Authentication of this login module must succeed. Always proceed to the next login module in this entry, irrespective of success or failure. |
requisite | Authentication of this login module must succeed. If success, proceed to the next login module; if failure, return immediately without processing the remaining login modules. |
sufficient | Authentication of this login module is not required to succeed. If success, return immediately without processing the remaining login modules; if failure, proceed to the next login module. |
optional | Authentication of this login module is not required to succeed. Always proceed to the next login module in this entry, irrespective of success or failure. |
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 |
|---|---|
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:
Example 7.3. Standard JAAS Properties
PropertiesLogin {
org.apache.activemq.jaas.PropertiesLoginModule required
org.apache.activemq.jaas.properties.user="users.properties"
org.apache.activemq.jaas.properties.group="groups.properties";
};The equivalent JAAS realm definition, using the jaas:config
element in a blueprint file, is shown in Example 7.4.
Example 7.4. Blueprint JAAS Properties
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.0.0" xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0"> <jaas:config name="PropertiesLogin"> <jaas:module className="org.apache.activemq.jaas.PropertiesLoginModule" flags="required"> org.apache.activemq.jaas.properties.user=users.properties org.apache.activemq.jaas.properties.group=groups.properties </jaas:module> </jaas:config> </blueprint>
![]() | Important |
|---|---|
You do not use double quotes for JAAS properties in the blueprint configuration. |
Fuse ESB Enterprise also provides an adapter that enables you to store JAAS authentication data in
an X.500 server. Example 7.5 defines the
LDAPLogin realm to use Fuse ESB Enterprise's LDAPLoginModule class, which
connects to the LDAP server located at ldap://localhost:10389.
Example 7.5. Configuring a JAAS Realm
<?xml version="1.0" encoding="UTF-8"?> <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.0.0" xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0"> <jaas:config name="LDAPLogin" rank="1"> <jaas:module className="org.apache.karaf.jaas.modules.ldap.LDAPLoginModule" flags="required"> initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory connection.username=uid=admin,ou=system connection.password=secret connection.protocol= connection.url = ldap://localhost:10389 user.base.dn = ou=users,ou=system user.filter = (uid=%u) user.search.subtree = true role.base.dn = ou=users,ou=system role.filter = (uid=%u) role.name.attribute = ou role.search.subtree = true authentication = simple </jaas:module> </jaas:config> </blueprint>
For a detailed description and example of using the LDAP login module, see Enabling LDAP Authentication.
Fuse MQ Enterprise supplies a JAAS login module that enables it to use LDAP to authenticate
users. The Fuse MQ Enterprise JAAS LDAP login module is implemented by the
org.apache.karaf.jaas.modules.ldap.LDAPLoginModule class. It is
preloaded in the container, so you do not need to install it's bundle.
To enable Fuse MQ Enterprise to use LDAP for user authentication you need to create a JAAS realm
that includes the Fuse MQ Enterprise LDAP login module. As shown in
Example 7.6, this is done by adding a
jaas:module element to the realm and setting its
className attribute to
org.apache.karaf.jaas.modules.ldap.LDAPLoginModule.
Example 7.6. Fuse ESB Enterprise LDAP JAAS Login Module
<jaas:config ... > <jaas:module className="org.apache.karaf.jaas.modules.ldap.LDAPLoginModule" flags="required"> ... </jaas:module> </jaas:config>
You will also need to provide values for the properties described in Table 7.2.
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
All of the properties are mandatory except the SSL properties.
Example 7.7 defines a JASS realm
that uses the LDAP server located at ldap://localhost:10389.
Example 7.7. Configuring a JAAS Realm that Uses LDAP Authentication
<?xml version="1.0" encoding="UTF-8"?> <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.0.0" xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0"> <jaas:config name="karaf" rank="1"> <jaas:module className="org.apache.karaf.jaas.modules.ldap.LDAPLoginModule" flags="sufficient"> initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory connection.username=uid=admin,ou=system connection.password=secret connection.protocol= connection.url = ldaps://localhost:10636 user.base.dn = ou=users,ou=system user.filter = (uid=%u) user.search.subtree = true role.base.dn = ou=roles,ou=system,dc=fusesource role.filter = (uid=%u) role.name.attribute = cn role.search.subtree = true authentication = simple ssl.protocol=SSL ssl.truststore=truststore ssl.algorithm=PKIX </jaas:module> ... </jaas:config> </blueprint>
When securing a container it is undesirable to use plain text passwords in configuration files. They create easy to target security holes. One way to avoid this problem is to use encrypted property placeholders when ever possible.
Fuse MQ Enterprise includes an extension to OSGi Blueprint that enables you to use Jasypt to decrypt property placeholders in blueprint files. It requires that you:
Create a properties file with encrypted values.
Add the proper namespaces to your blueprint file.
Import the properties using the Aries property placeholder extension.
Configure the Jasypt encryption algorithm.
Use the placeholders in your blueprint file.
Ensure that the Jasypt features are installed into the Fuse MQ Enterprise container.
Encrypted properties are stored in plain properties files. They are identified by
wrapping them in the ENC() function as shown in
Example 7.8.
Example 7.8. Property File with an Encrypted Property
#ldap.properties ldap.password=ENC(amIsvdqno9iSwnd7kAlLYQ==) ldap.url=ldap://192.168.1.74:10389
![]() | Important |
|---|---|
You will need to remember the password and algorithm used to encrypt the values. You will need this information to configure Jasypt. |
To use encryted properties in your configuration, you will need to add the following namespaces to your blueprint file:
Aries extensions—http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0
Apache Karaf Jasypt—http://karaf.apache.org/xmlns/jasypt/v1.0.0
Example 7.9 shows a blueprint file with the required namespaces.
Example 7.9. Encrypted Property Namespaces
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0" xmlns:enc="http://karaf.apache.org/xmlns/jasypt/v1.0.0"> ... </blueprint>
In order to use encrypted property placeholders in a blueprint file you need to include
an Aries property-paceholder element to you blueprint file. As shown in
Example 7.10, it must come before the Jasypt
configuration or the use of placeholders.
Example 7.10. Aries Placeholder Extension
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0" xmlns:enc="http://karaf.apache.org/xmlns/jasypt/v1.0.0"> <ext:property-placeholder> <location>file:etc/ldap.properties</location> </ext:property-placeholder> ... </blueprint>
The Aries property-paceholder element's
location child specifies the location of the property file
that contains the properties to use for the configuration. You can specify multiple files
by using multiple location children.
You configure Jasypt using the Apache Karaf property-placeholder
element. It has one child, encoder, that contains the actual
Jasypt configuration.
The encoder element's mandatory
class attribute specifies the fully qualified classname of the
Jasypt encryptor to use for decrypting the properties. The
encoder element can take a property
child that defines a Jasypt PBEConfig bean for configuring the
encryptor.
For detailed information on how to configure the different Jasypt encryptors, see the Jasypt documentation.
Example 7.11 shows configuration for using the string encryptor and retrieving the password from an environment variable.
Example 7.11. Jasypt Blueprint Configuration
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0" xmlns:enc="http://karaf.apache.org/xmlns/jasypt/v1.0.0"> <ext:property-placeholder> <location>file://ldap.properties</location> <enc:property-placeholder> <enc:encryptor class="org.jasypt.encryption.pbe.StandardPBEStringEncryptor"> <property name="config"> <bean class="org.jasypt.encryption.pbe.config.EnvironmentStringPBEConfig"> <property name="algorithm" value="PBEWithMD5AndDES" /> <property name="passwordEnvName" value="FUSE_ENCRYPTION_PASSWORD" /> </bean> </property> </enc:encryptor> </enc:property-placeholder> ... </blueprint>
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.
Example 7.12. Jasypt Blueprint Configuration
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0" xmlns:enc="http://karaf.apache.org/xmlns/jasypt/v1.0.0"> <ext:property-placeholder> <location>file://ldap.properties</location> <enc:property-placeholder> <enc:encryptor class="org.jasypt.encryption.pbe.StandardPBEStringEncryptor"> <property name="config"> <bean class="org.jasypt.encryption.pbe.config.EnvironmentStringPBEConfig"> <property name="algorithm" value="PBEWithMD5AndDES" /> <property name="passwordEnvName" value="FUSE_ENCRYPTION_PASSWORD" /> </bean> </property> </enc:encryptor> </enc:property-placeholder> <jaas:config name="karaf" rank="1"> <jaas:module className="org.apache.karaf.jaas.modules.ldap.LDAPLoginModule" flags="required"> initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory debug=true connectionURL=${ldap.url} connectionUsername=cn=mqbroker,ou=Services,ou=system,dc=fusesource,dc=com connectionPassword=${ldap.password} connectionProtocol= authentication=simple userRoleName=cn userBase = ou=User,ou=ActiveMQ,ou=system,dc=fusesource,dc=com userSearchMatching=(uid={0}) userSearchSubtree=true roleBase = ou=Group,ou=ActiveMQ,ou=system,dc=fusesource,dc=com roleName=cn roleSearchMatching= (member:=uid={1}) roleSearchSubtree=true </jaas:module> </jaas:config> </blueprint>
The ${ldap.password} placeholder will be replaced with the decrypted value
of the ldap.password property from the properties file.
By default, Fuse ESB Enterprise does not have the Jasypt encryption libraries installed. In order
to use encrypted property placeholders, you will need to install the
jasypt-encryption feature using Fuse MQ Enterprise's
features:install command as shown in
Example 7.13.
By configuring each of the administrative functions to use a different role for authorization, you can provide fine grained control over who can monitor and manipulate running containers.
You can independently configure roles for the following different administrative protocols:
SSH (remote console login)
JMX management
The default role name for all of the administration protocols is set by the
karaf.admin.role property in the Fuse MQ Enterprise's
etc/system.properties file. For example, the default setting of
karaf.admin.role is:
karaf.admin.role=admin
You have the option of overriding the default admin role set by
karaf.admin.role for each of the administrative protocols.
The default mode for running a Fuse MQ Enterprise broker is to run in daemon mode. In this mode, the broker runs as a background process and you have no direct means for managing it or requesting status information. You can access a broker in daemon mode in the following ways:
the Fuse MQ Enterprise administration client that can be used to send any of the console commands to a broker running in daemon mode
a broker running in console mode can connect to a remote broker and be used to manage the remote broker
Fuse MQ Enterprise includes a vanilla Apache Karaf shell that can connect to a remote broker and be used to manage the remote broker
If a broker is started in console mode, you can simply enter commands directly in the command console.
The Fuse MQ Enterprise administration client is run using the client in
.
Example 8.1 shows the syntax for the command.InstallDir/bin
Example 8.1. Client Command
client [--help] [-a port] [-h host] [-u user] [-p password] [-v] [-r attempts] [-d delay] [commands]
Table 8.1 describes the command's arguments.
Table 8.1. Administration Client Arguments
| Argument | Description |
|---|---|
--help | Displays the help message. |
-a | Specifies the remote host's port. |
-h | Specify the remote host's name. |
-u | Specifies user name used to log into the broker. |
-p | Specifies the password used to log into the broker. |
-v | Use verbose output. |
-r | Specifies the maximum number of attempts to establish a connection. |
-d | Specifies, in seconds, the delay between retries. The default is 2 seconds. |
commands | Specifies one or more commands to run. If no commands are specified, the client enters an interactive mode. |
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.
Example 8.2. Console Help
FuseMQ:karaf@root>helpCOMMANDS activemq:browse activemq:bstat activemq:list activemq:purge activemq:query admin:change-opts Changes the Java options of an existing container instance. admin:change-rmi-registry-port Changes the RMI registry port (used by management layer) of an existing container instance....FuseMQ:karaf@root>
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.
Example 8.3. Help for a Command
FuseMQ:karaf@root>admin:start --helpDESCRIPTION admin:start Starts an existing container instance. SYNTAX admin:start [options] name ARGUMENTS name The name of the container instance OPTIONS --help Display this help message -o, --java-opts Java options when launching the instanceFuseMQ:karaf@root>
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.
Fuse MQ Enterprise includes a shell command that will open a vanilla command console without starting a broker instance. You can use this command console to connect to remote brokers in the same way as you would a broker's command console.
The remote client can execute any of the broker's console commands. For a complete list of commands see the Console Reference .
In most large messaging environments there will be multiple brokers deployed. This may be for load management, high availability, or other business reasons. Using standalone brokers this requires manually installing and configuring multiple instances of Fuse MQ Enterprise. Using a fabric, however, you can deploy multiple brokers from a single location and easily reuse large portions of the configuration.
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.
Deploying a new standalone broker involves installing Fuse MQ Enterprise on a new machine and modifying its configuration as needed. You will need to do this for all of the additional brokers in your deployment.
To deploy a new standalone broker:
Install Fuse MQ Enterprise onto the target system as described in Installation Guide.
Modify the new installation's configuration for your environment as described in Editing a Broker's Configuration.
You will need to repeat this process for each standalone broker you want to deploy.
For more information on configuring brokers to work together see:
Deploying a new broker instance into a fabric involves creating a new broker profile and deploying it to a Fabric Container. The fabric infrastructure simplifies these tasks by:
allowing you to do them from a remote location
providing tools that assist in automatically configuring fail over clusters, networks of brokers, and master/slave clusters.
allowing you to reuse parts of existing profiles to ensure consistency
providing tooling to do rolling updates
providing tooling to roll back changes when needed
From the Fuse MQ Enterprise console you can use the fabric:mq-create to create new broker profiles and new containers for the brokers. You can also use Fuse Management Console to perform to create the profiles and assign them to containers.
To deploy a new broker into a fabric:
Create a template Fuse MQ Enterprise XML configuration file in a location that is accessible to the container.
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.
Example 9.1. Uploading a Template to a Fabric Ensemble
FuseESB:karaf@root>fabric:import -t /fabric/configs/versions/version/profiles/mq-base/configFileconfigFile
version must match the version of the new profile you
will create for the new broker.
Use the fabric:mq-create command to create a profile for the new broker and assign it to a container.
To deploy the new broker into an existing container use the command shown in Example 9.2
Example 9.2. Creating a New Broker in an Existing Container
FuseESB:karaf@root>fabric:mq-create --assign-containercontainerName--configconfigFileprofileName
This will create a new broker profile that inherits from the mq-base
profile, but uses your XML configuration template, and deploy it to the specified
container.
To deploy the new broker into an new container use the command shown in Example 9.3
Example 9.3. Creating a New Broker in a New Container
FuseESB:karaf@root>fabric:mq-create --create-containercontainerName--configconfigFileprofileName
This will create a new broker profile that inherits from the mq-base
profile, but uses your XML configuration template, create a new container named
containerName, and deploy the broker profile to it.
![]() | Note |
|---|---|
The new container will be a child of the container from which you execute the fabric:mq-create command. |
![]() | Tip |
|---|---|
You can add network configuration settings to the profile as well. See fabric:mq-create in Console Reference. |
Use the fabric:profile-edit command shown in Example 9.4 to set the required properties.
Example 9.4. Editing a Broker Profile
FuseESB:karaf@root>fabric:profile-edit --pid org.fusesource.mq.fabric.server-profileName/property=valueprofileName
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 |
|---|---|
Fuse Management Console makes this process easier by providing a Web based UI. |
For more information on configuring brokers to work together see:
For more information on using Fuse Management Console see the Fuse Management Console Documentation.
![]() | Important |
|---|---|
If the broker is running in console mode it can only be shutdown locally. |
The method used to stop a broker running on the machine you logged into depends on the mode in which the broker is running. If it is running in console mode, you use one of the console commands to shut down the broker. If it is running in daemon mode, the broker doesn't have a command console. So, you need to use one of the utility commands supplied with Fuse MQ Enterprise.
If you launched Fuse MQ Enterprise by running fusemq, you shut it down using the shutdown -f command as shown in Example 10.1.
Example 10.1. Using the Console's Shutdown Command
FuseMQ:karaf@root>shutdown -fFuseMQ:karaf@root>logout [Process completed]
![]() | Tip |
|---|---|
CTRL+D will also shutdown the broker. |
If you launched Fuse MQ Enterprise by running the start command, log in to
the machine where the broker is running and run the stop command in
the broker installation's bin folder.
![]() | Tip |
|---|---|
You can stop a broker running in daemon mode remotely. See Shutting Down a Broker Remotely. |
For many use cases logging into the machine running a broker instance is impractical. In those cases, you need a way to stop a broker from a remote machine. Fuse MQ Enterprise offers a number of ways to accomplish this task:
using the stop command—the stop command does not require starting an instance of the broker
using a remote console connection—a broker's console can be used to remotely shutdown a broker on another machine
using a fabric member's console—brokers that are part of a fabric can stop members of their fabric
using Fuse Management Console—brokers that are part of a fabric can be stopped using an Fuse Management Console connected to their fabric
For more information see the Fuse Management Console Documentation.
You can stop a remote instance without starting up Fuse ESB Enterprise on your local host by running
the stop command in the
directory. The commands
syntax is shown in Example 10.2.InstallDir/bin
-a portSpecifies the SSH port of the remote instance. The default is 8101.
-h hostnameSpecifies the hostname of the machine on which the remote instance is running.
-u usernameSpecifies the username used to connect to the remote broker.
![]() | Tip |
|---|---|
The default username for a broker is |
-p passwordSpecifies the password used to connect to the remote broker.
![]() | Tip |
|---|---|
The default password for a broker is |
Example 10.3 shows how to stop a remote broker on a
machine named NEBrokerHost2.
Fuse MQ Enterprise's console can be connected to a remote broker using the
ssh:ssh command. Once the console is connected to the remote
broker, you can shut it down by running the osgi:shutdown command.
Example 10.4 shows the command sequence for using a remote
console connection to shutdown a broker running on a machine named
NWBrokerHost.
Example 10.4. Shutting DOwn a Broker using a Remote Console Connection
FuseMQ:karaf@root>ssh -l karaf -P karaf NWBrokerHost| ___| | \/ || _ | | |_ _ _ ___ ___ | . . || | | | | _|| | | |/ __| / _ \ | |\/| || | | | | | | |_| |\__ \| __/ | | | |\ \/' / \_| \__,_||___/ \___| \_| |_/ \_/\_\ Fuse MQ (7.0.0.fuse-beta-040) http://fusesource.org/mq/ Hit '<tab>' for a list of available commands and '[cmd] --help' for help on a specific command. Hit '<ctrl-d>' or 'osgi:shutdown' to shutdown Fuse MQ.FuseMQ:karaf@root>osgi:shutdownConfirm: shutdown instance root (yes/no):yesFuseMQ:karaf@root>FuseESB:karaf@root>
![]() | Important |
|---|---|
Pressing Control+D when connected to a remote broker closes the remote connection and returns you to the local shell. |
If the broker you want to shutdown is part of a fabric, you can shut it down from any of the brokers in the fabric using the fabric:container-stop console command. fabric:container-stop takes the name of the fabric container hosting the broker as an argument. The command can be run either from a broker in console mode or using the broker's administration client.
Example 10.5 shows how to use the administration client to
shutdown a broker running in a container named fabric-broker3.
For more information see fabric:container-stop, in Console Reference.
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 |
|---|---|
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.
When a broker joins a fabric as a managed container, it stops being a broker because
the default behavior of the fabric:join command is to wipe out the
container's configuration and replace it with the fabric profile. To start up
as broker, you need to ensure that the fabric has a profile with the proper configuration
and associate it with the container. The fabric:join command's
-p argument allows you to specify a profile to install into the container
once the agent is installed.
Several things happen when a broker joins a fabric as a managed container:
The broker installs the required Fuse Fabric bundles to interact with the fabric's ensemble.
The broker contacts the specified Fabric Server and initiates the joining process.
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 |
|---|---|
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 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.
The ensemble installs the fabric profile into the container.
This loads the Fabric Agent into the container to facilitate the management of the container.
If the -p argument is passed the fabric:join,
the container's agent installs the artifacts and configuration settings from the
specified profile.
The container sits empty and ready for you to associate one or more profiles with it.
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.
Joining a fabric as a managed container converts a standalone broker into a vanilla fabric container. It can take on any characteristics that are required. If you want it to join the fabric and continue to function as a message broker, then you must ensure that the fabric being joined has a profile that will configure the container to be a message broker and assign that profile to the container.
The default set of profiles installed with Fuse Fabric include an mq profile
that loads a default message broker. You can also create a new profile for your brokers as
described in Editing a Broker's Configuration in a Fabric.
The easiest way to assign the profile is to do so when executing the
fabric:join by using the -p flag. The specified
profile will be assigned to the container as soon as the agent is installed. If you would
rather do it in two steps, you can assign the profile using the
fabric:container-change-profile command or Fuse Management Console.
To join a broker to a fabric and have it start up as a broker:
Create a profile for your broker.
For details on creating a broker profile see Editing a Broker's Configuration in a Fabric.
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:
Connect to the command console of one of the containers in the fabric.
Enter the following sequence of console commands:
FuseMQ:karaf@root>config:edit org.fusesource.fabric.zookeeperFuseMQ:karaf@root>config:proplistservice.pid = org.fusesource.fabric.zookeeper zookeeper.url = myhostA:2181,myhostB:2181,myhostC:2181,myhostC:2182,myhostC:2183 fabric.zookeeper.pid = org.fusesource.fabric.zookeeperFuseMQ: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.
Connect to the standalone broker's command console.
Enter the following command:
FuseMQ:karaf@root>fabric:join -pbrokerProfilefabricURLbrokerName
You need to provide values for:
For details on fabric:join see fabric:join in Console Reference.
When a broker joins a fabric as a non-managed container, it continues being a standalone broker because a Fabric Agent does not take control of the container. The agent only registers the broker with the fabric's ensemble and keeps the registry entries for it up to date. This enables consumers to discover the broker using the fabric's discovery mechanism described in Fuse Fabric Discovery Agent in Using Networks of Brokers.
Several things happen when a broker joins a fabric as a non-managed container:
The broker installs the required Fuse Fabric bundles to interact with the fabric's ensemble.
The broker contacts the specified Fabric Server and initiates the joining process.
The Fabric Server registers the container with the fabric's ensemble.
This adds the broker's information to the fabric's registry using the broker's name as the key. Because the broker is non-managed, the registry creates an entry containing information for all the message destinations hosted by the broker.
![]() | 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. |
The agent monitors the broker and updates the updates the ensemble's registry entry as needed.
To join a broker to a fabric a non-managed container:
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:
Connect to the command console of one of the containers in the fabric.
Enter the following sequence of console commands:
FuseMQ:karaf@root>config:edit org.fusesource.fabric.zookeeperFuseMQ:karaf@root>config:proplistservice.pid = org.fusesource.fabric.zookeeper zookeeper.url = myhostA:2181,myhostB:2181,myhostC:2181,myhostC:2182,myhostC:2183 fabric.zookeeper.pid = org.fusesource.fabric.zookeeperFuseMQ: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.
Connect to the standalone broker's command console.
Enter the following command:
FuseMQ:karaf@root>fabric:join -nfabricURLbrokerName
You need to provide values for:
-n—specifies that the broker will
not be managed by the fabric
fabricURL—the Fabric Server URL you obtained
in Step 1
brokerName—the name the broker will use to
register with the fabric
![]() | Important |
|---|---|
The name should be unique among the containers in the fabric. |
For details on fabric:join see fabric:join in Console Reference.
If there is no existing fabric for a broker to join, you will need to create one from the standalone broker. There are two options for how to do this:
The recommended approach is to create the fabric such that the broker is converted into a managed Fabric Server. The container will revert to being a vanilla broker, so you will need to either create a new broker with the desired configuration or deploy an updated broker profile into the Fabric Server.
Ensuring that the new broker is configured properly requires creating a broker profile with the proper settings. This can be done once the new fabric is created using the fabric:mq-create command. The fabric:mq-create command can also create the new broker.
The alternative approach is to create the fabric such that the broker becomes a non-managed Fabric Server. The broker becomes a Fabric Server that is fully capable of being part of a fabric's ensemble. However, the broker retains control over its own configuration. It will continue to be managed as if it were a standalone broker and will not respond to fabric commands that attempt to alter its configuration.
Several things happen when a fabric is created from a standalone broker:
The broker installs the required Fuse Fabric bundles to become a Fabric Server.
The Fabric Server starts up the ensemble process.
A new ensemble containing an empty configuration registry and a runtime registry with a single entry for the Fabric Server is created.
The Fabric Server delegates control over its configuration to the ensemble.
![]() | Note |
|---|---|
If the fabric is created with a non-managed server, this step is skipped. |
The ensemble associates the profiles required to be a Fabric Server with the container.
Unless the --no-import flag is used, the ensemble imports a set of
profiles.
If the --import-dir flag is used, the profiles are imported
from the specified location.
If no location is specified the default set of profiles is imported from
.InstallDir/fabric/import
The ensemble installs the default mq profile to the container.
This starts a default broker instance in the container.
![]() | Note |
|---|---|
If the fabric is created with a non-managed server, this step is skipped. |
The ensemble waits for commands to update the fabric.
To create a new fabric from a standalone broker:
Delete the standalone broker configuration(s) from your installation's
/etc folder.
The configuration is stored in
/etc/org.fusesource.mq.fabric.server-.configName.cfg
Connect to the standalone broker's command console.
Remove any brokers running in the container.
Use config:list to locate any PIDs using the form
org.fusesource.mq.fabric.server..ID
Use config:delete to delete all of the PIDs using the form
org.fusesource.mq.fabric.server..ID
Enter the following command:
FuseMQ:karaf@root>fabric:create
![]() | Tip |
|---|---|
If you want to import a predefined set of profiles, use the
|
For details on fabric:create see fabric:create in Console Reference.
Add a new broker to the fabric as described in Deploying a New Broker into a Fabric.
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
The logging system is configured by a combination of two OSGi Admin PIDs and one configuration file:
etc/system.properties—the configuration file that sets the
logging level during the broker’s boot process. The file contains a single property,
org.ops4j.pax.logging.DefaultServiceLog.level, that is set to
ERROR by default.
org.ops4j.pax.logging—the PID used to configure the
logging back end service. It sets the logging levels for all of the defined loggers
and defines the appenders used to generate log output. It uses standard Log4j
configuration. By default, it sets the root logger's level to INFO and
defines two appenders: one for the console and one for the log file.
![]() | Tip |
|---|---|
The console's appender is disabled by default. To enable it, add
|
org.apache.karaf.log.cfg—configures the output of the
log console commands.
The most common configuration changes you will make are changing the logging levels, changing the threshold for which an appender writes out log messages, and activating per bundle logging.
The default logging configuration sets the logging levels so that the log file will provide enough information to monitor the behavior of the runtime and provide clues about what caused a problem. However, the default configuration will not provide enough information to debug most problems.
The most useful logger to change when trying to debug an issue with Fuse MQ Enterprise is the root
logger. You will want to set its logging level to generate more fine grained messages. To do
so you change the value of the org.ops4j.pax.logging PID's
log4j.rootLogger property so that the logging level is one of the following:
TRACE
DEBUG
INFO
WARN
ERROR
FATAL
NONE
Example 12.1 shows the commands for setting the root loggers log level in a standalone broker.
Example 12.1. Changing Logging Levels
FuseMQ:karaf@root>config:edit org.ops4j.pax.loggingFuseMQ:karaf@root>config:propset log4j.rootLogger "DEBUG, out, osgi:VmLogAppender"FuseMQ:karaf@root>config:update
When debugging a problem in Fuse MQ Enterprise you may want to limit the amount of logging
information that is displayed on the console, but not the amount written to the log file.
This is controlled by setting the thresholds for each of the appenders to a different
level. Each appender can have a
log4j.appender. property that
controls what level of messages are written to the appender. The appender threshold values
are the same as the log level values.appenderName.threshold
Example 12.2 shows an example of setting the root
logger to DEBUG but limiting the information displayed on the console to
WARN.
Example 12.2. Changing the Log Information Displayed on the Console
FuseESB:karaf@root>config:edit org.ops4j.pax.loggingFuseMQ:karaf@root>config:propset log4j.rootLogger "DEBUG, out, osgi:VmLogAppender"FuseMQ:karaf@root>config:propappend log4j.appender.stdout.threshold WARNFuseMQ:karaf@root>config:update
There are three ways you can view the log:
using a text editor
using the broker's, or a remote broker's, console
using the administration client
The log files are stored as simple text files in
. The main log file is
InstallDir/data/logkaraf.log. If archiving is turned on, there may be archived log files
also stored in the logging directory.
Log entries are listed in chronological order with the oldest entries first. The default output displays the following information:
the time of the entry
the log level of the entry
the thread that generated the entry
the bundle that generated the entry
an informational message about the cause of the entry
The Fuse MQ Enterprise console provides the following commands for viewing the log:
log:display—displays the most recent log entries
By default, the number of entries returned and the pattern of the output depends on
the size and pattern properties in the
org.apache.karaf.log.cfg file. You can override these using the
-p and -d arguments.
log:display-exception—displays the most recently logged exception
log:tail—continuously display log entries
For more information on using these commands see Log Console Commands in Console Reference.
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.
By default a broker is set up to allow for JMX management. It uses the JVM's MBean
server and creates its own JMX connector at
service:jmx:rmi:///jndi/rmi://.
If the default configuration does not meet the needs of the deployment environment, the broker
provides configuration properties for customizing most aspects of its JMX behavior. For
instance, you can completely disable JMX for a broker. You can also force the broker to
create its own MBean server.hostname:1099/jmxrmi
By default JMX is enabled for a Fuse MQ Enterprise broker. To disable JMX entirely you simply
set the broker element's useJmx
attribute to false. This will stop the broker from exposing itself
via JMX.
![]() | Important |
|---|---|
Disabling JMX will also disable the commands in the activemq shell. |
In a production environment it is advisable to secure the access to your brokers'
management interfaces. To set up authentication To override the default role for JMX access
add a jmxRole property to the
etc/org.apache.karaf.management.cfg file.
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.
Table 13.1. Broker JMX Configuration Properties
| Property | Default Value | Description |
|---|---|---|
useMBeanServer
| true | Specifies whether the broker will use the MBean server created by the JVM. When
set to false, the broker will create an MBean server. |
jmxDomainName
| org.apache.activemq | Specifies the JMX domain used by the broker's MBeans. |
createMBeanServer
| true | Specifies whether the broker creates an MBean server if none is found. |
createConnector
| true[a] | Specifies whether the broker creates a JMX connector for the MBean server. If
this is set to false the broker will only be accessible
using the JMX connector created by the JVM. |
connectorPort
| 1099 | Specifies the port number used by the JMX connector created by the broker. |
connectorHost
| localhost | Specifies the host used by the JMX connector and the RMI server. |
rmiServerPort
| 0 | Specifies the RMI server port. This setting is useful if port usage needs to be restricted behind a firewall. |
connectorPath
| /jmxrmi | Specifies the path under which the JMX connector will be registered. |
[a] The
default configuration template for the broker sets this property to
| ||
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.
Example 13.1. Configuring a Broker's JMX Connection
<broker ... > ... <managementContext> <managementContext createMBeanServer="false" createConnector="false" /> </managementContext> ... </broker>
Table 13.2 describes the statistics collected for a broker.
Table 13.2. Broker JMX Statistics
Table 13.3 describes the statistics collected for a destination.
Table 13.3. Destination JMX Statistics
Table 13.4 describes the statistics collected for a subscription.
Table 13.4. Connection JMX Statistics
The MBeans exposed by Fuse MQ Enterprise provide a number of operations for monitoring and managing a broker instance. You can access these operations through any tool that supports JMX.
Table 13.5 describes the operations exposed by the MBean for a broker.
Table 13.5. Broker MBean Operations
Table 13.6 describes the operations exposed by the MBean for a transport connector.
Table 13.6. Connector MBean Operations
Table 13.7 describes the operations exposed by the MBean for a network connector.
Table 13.8 describes the operations exposed by the MBean for a queue destination.
Table 13.8. Queue MBean Operations
Table 13.9 describes the operations exposed by the MBean for a topic destination.
Table 13.9. Topic MBean Operations
Table 13.10 describes the operations exposed by the MBean for a durable subscription.
Table 13.10. Subscription MBean Operations
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 |
|---|---|
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:
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.
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 |
|---|---|
The
patch:list
command will display a list of all patches added to the broker's
|
Review the simulation log to understand the changes that will be made to the broker.
Apply the patch to the broker using the patch:install command.
![]() | Tip |
|---|---|
The
patch:list
command will display a list of all patches added to the broker's
|
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.
Occasionally a patch will not work or introduce new issues to a broker. In these cases you can easily back the patch out of the system and restore it pre-patch behavior using the patch:rollback command. As shown in Example 14.2, the command takes the name of patch to be backed out.
![]() | Tip |
|---|---|
The
patch:list
command will display a list of all patches added to the broker's
|
The broker will need to restart to rollback 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.
The bundles loaded by a broker in a fabric is controlled by the broker's Fabric Agent. The agent inspects the profiles applied to the broker to determine what bundles to load, and the version of each bundle, and then loads the specified version of each bundle for the broker.
A patch typically includes a new version of one or more bundles, so to apply the patch to broker in a fabric you need to update the profiles applied to it. This will cause the Fabric Agent to load the patched versions of the bundles.
Fuse Management Console is the recommended tool for patching brokers in a fabric. However, the command console's fabric shell also provides the commands needed to patch brokers running in a fabric.
Patching a broker in a fabric involves:
Getting a patch file.
Customer Support sends you a patch.
Customer Support sends you a link to download a patch.
Uploading one or more patch files to the fabric's Maven repository.
Applying the patch(es) to a profile version.
This creates a new profile version that points to the new versions of the patched bundles and repositories.
Migrate one or two brokers to the patched profile version to ensure that the patch does not introduce any new issues.
After you are certain that the patch works, migrate the remaining brokers in the fabric to the patched version.
Fuse Management Console is the easiest and most verbose method of patching brokers in a fabric. The Fuse Management Console Patching tab uploads patches to a fabric's Maven repository and applies the patch to a specified profile version. You can then use Fuse Management Console to roll the patch out to all of the containers in the fabric.
The Fuse MQ Enterprise command console can also be used to patch brokers running in a fabric. To patch a fabric broker:
Upload the patch file to the fabric's Maven repository.
Create a new profile version to which the patch will be applied.
Modify all of the profiles in the new version which require the patch.
Use the fabric:container-upgrade command to roll the patch out to the brokers running in the fabric.
To simplify deploying Fuse MQ Enterprise it is recommended that you place the
activemq-all.jar file on the broker's CLASSPATH. It
contains all of the classes needed by a message broker. This is the default set up for a
Fuse MQ Enterprise installation.
However, if you want more control over the JARs in the broker's CLASSPATH
you can add the individual JARs. There are several JARs that are required. In addition,
there are a few that are only needed when certain features are used.
The following JARs are installed with Fuse MQ Enterprise and must be placed on the broker's
CLASSPATH:
activemq-core.jar
activeio-core.jar
slf4j-api.jar
The JARs containing the JEE APIs are also required by the broker. These could be located in one of the following locations:
the jee.jar from Oracle
your JEE container's installation
the Geronimo specs JARs:
geronimo-spec-jms.jar
geronimo-spec-jta.jar
geronimo-spec-j2ee-management.jar