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.

Understanding the Fuse MQ Enterprise Configuration Model

Overview

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

Figure 1.1. Fuse MQ Enterprise Configuration System

the configuration template is combined with a default PID and one or more container created PIDs

Configuration templates

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

configuration templates use property placeholders for settings that will be controlled via the OSGi Admin service
configuration templates do not configure the broker's name
configuration templates do not configure the location of the data directory
configuration templates do not configure transport connectors
configuration templates do not configure network connectors
configuration templates do not control if a broker is a master or a slave node
configuration templates can be used as a baseline for multiple brokers on the same machine

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

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

Example 1.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 1.2 uses three property placeholders that allow you to modify the base configuration using fabric properties.

Example 1.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>

OSGi PIDs

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.

Editing a Standalone Broker's Configuration

Revision History

Overview

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.

Editing the configuration template

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.

Editing the OSGi properties

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.id. The id 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.

Config shell

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.

Editing a Broker's Configuration in a Fabric

Revision History

Overview

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.

Profiles

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.

Procedure

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.

Chapter 2. Setting up and Accessing the Fuse MQ Enterprise Web Console

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.

Revision History

Using the Embedded Console
Securing the Web Console
Deploying a Standalone Console

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.

	Note
	For monitoring a broker hosted in a Fabric container, use Fuse Management Console. The Fuse MQ Enterprise Web console does not work in a Fabric container.

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.

Using the Embedded Console

Revision History

Overview

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.

	Note
	When a broker is deployed into a fabric, the default configuration profile does not include the Web console. The Fuse MQ Enterprise Web console does not work in a Fabric container, so to achieve similar functionality you can use Fuse Management Console

The default port and security configuration can easily be modified.

Accessing the console

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 .

Changing the port

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 2.1 shows the console commands used to change the port number of a standalone broker's Web console to 8536.

Example 2.1. Changing the Web Console's Port

FuseMQ:karaf@root> config:edit org.ops4j.pax.web
FuseMQ:karaf@root> config:proplist
   service.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.web
FuseMQ:karaf@root> config:propset org.osgi.service.http.port 8536
FuseMQ:karaf@root> config:update

Securing the console

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.

Securing the Web Console

Overview

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.

Enabling basic authentication

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.

Editing user credentials

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

Enabling SSL security

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

Example 2.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 ActiveMQ 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 `broker.ks` certificate used in the example is insecure. Anyone can access its private key. To secure your system properly, you must create new certificates signed by a trusted CA, as described in Managing Certificates in ActiveMQ Security Guide.

Reference

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.

Deploying a Standalone Console

Revision History

Overview

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.

Disabling the embedded console

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

Example 2.3. Disabling the Embedded Web Console

<beans  ... >

  <broker ... >
     ...
  </broker>

  <!-- <import resource="jetty.xml"/>  -->

</beans>

Configuring Tomcat

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 TOMCAT_HOME/webapps folder.
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 TOMCAT_HOME/common/lib folder.

Modify TOMCAT_HOME/bin/catalina.sh(.bat) to include the configuration in Example 2.4.

Example 2.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.

Monitoring clusters

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 2.5 shows the properties for monitoring a cluster using the Web console.

Example 2.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.

Chapter 3. Deploying a New Broker Instance

Fuse ESB Enterprise supports the deployment of multiple JMS brokers in a container. Doing so involves creating a new set of broker configurations and deploying them to the container.

Overview

Deploying a new broker instance involves creating a new OSGi broker configuration and deploying it into the container. In a standalone Fuse ESB Enterprise container this can be done from the command console using the config command shell. For containers deployed in a fabric, you need to either create a profile for the new broker, or modify an existing profile to include the new broker configuration.

You will also likely want to create a new Apache ActiveMQ template configuration file that allows you to modify the desired settings. This will involve creating a new Apache ActiveMQ XML file and making it accessible to container.

Standalone containers

To deploy a new broker into a standalone Fuse ESB Enterprise container:

Create a template Apache ActiveMQ XML configuration file in a location that is accessible to the container.
In the Fuse ESB Enterprise command console, use the config:edit command to create a new OSGi configuration file.
Important
The PID must start with org.fusesource.mq.fabric.server-.
Use the config:propset command to associate your template XML configuration with the broker OSGi configuration as shown in Example 3.1.
Example 3.1. Specifying a Broker's Template XML Configuration
```
FuseESB:karaf@root> config:propset config configFile
```
Use the config:propset command to set the required properties.
The properties that need to be set will depend on the properties you specified using property place holders in the template XML configuration and the broker's network settings.
For information on using config:propset see config:propset, in Console Reference.
Save the new OSGi configuration using the config:update command.

Once the new OSGi configuration is saved the new broker instance will start.

	Tip
	If you want to simply deploy a second broker that uses the default configuration template skip Step 1. You will need set the config property to `${karaf.base}/etc/activemq.xml`. You will also need to provide values for the data property, the broker-name property, and the openwire-port property.

Fabric containers

To deploy a new broker into an Fuse ESB Enterprise container in a fabric:

Create a template Apache ActiveMQ XML configuration file in a location that is accessible to the container.
In the Fuse ESB Enterprise command console, use the fabric:import command to upload the your XML configuration template to the Fabric Ensemble as shown in Example 3.2.
Example 3.2. Uploading a Template to a Fabric Ensemble
```
FuseESB:karaf@root> fabric:import -t /fabric/configs/versions/version/profiles/mq-base/configFile configFile
```
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 3.3
  Example 3.3. Creating a New Broker in an Existing Container
  FuseESB:karaf@root> fabric:mq-create --assign-container containerName --config configFile profileName
  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 3.4
  Example 3.4. Creating a New Broker in a New Container
  FuseESB:karaf@root> fabric:mq-create --create-container containerName --config configFile profileName
  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 3.5 to set the required properties.
Example 3.5. Editing a Broker Profile
```
FuseESB:karaf@root> fabric:profile-edit --pid org.fusesource.mq.fabric.server-profileName/property=value profileName
```
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
	If you want to simply deploy a second broker that uses the default configuration template skip Step 1 and Step 2.

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

Example

If you wanted to deploy a new instance of the default broker called myBroker that stores its data in InstallDir/data/myBroker and opens a port at 61617, you would do the following:

Open the Fuse ESB Enterprise command console.
In the Fuse ESB Enterprise command console, use the config:edit command to create a new OSGi configuration file:
```
FuseESB:karaf@root> config:edit org.fusesource.mq.fabric.server-myBroker
```
Use the config:propset command to associate your template XML configuration with the broker OSGi configuration:
```
FuseESB:karaf@root> config:propset config ${karaf.base}/etc/activemq.xml
```
Use the config:propset command to specify the new broker's data directory:
```
FuseESB:karaf@root> config:propset data ${karaf.data}/myBroker
```
Use the config:propset command to specify the new broker's name:
```
FuseESB:karaf@root> config:propset broker-name myBroker
```
Use the config:propset command to specify the new broker's openwire port:
```
FuseESB:karaf@root> config:propset openwire-port 61617
```
Save the new OSGi configuration using the config:update command.

More information

For more information on creating Apache ActiveMQ templates and Apache ActiveMQ OSGi configuration see Editing a Broker's Configuration.

For information about updating container's in a fabric using Fuse Management Console see the Fuse Management Console Documentation.

Chapter 4. Using Logging

The broker's log contains information about all of the critical events that occur in the broker. You can configure the granularity of the logged messages to provide the required amount of detail.

Logging Configuration
Viewing the Log

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

Logging Configuration

Revision History

Overview

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 log4j.appender.stdout.append=true to the configuration For example, to enable the console appender in a broker, you would use the following commands:

FuseMQ:karaf@root> config:edit org.ops4j.pax.logging
FuseMQ:karaf@root> config:propappend log4j.appender.stdout.append true
FuseMQ:karaf@root> config:update

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.

Changing the log levels

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 4.1 shows the commands for setting the root loggers log level in a standalone broker.

Example 4.1. Changing Logging Levels

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

Changing the appenders' thresholds

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.appenderName.threshold property that controls what level of messages are written to the appender. The appender threshold values are the same as the log level values.

Example 4.2 shows an example of setting the root logger to DEBUG but limiting the information displayed on the console to WARN.

Example 4.2. Changing the Log Information Displayed on the Console

FuseESB:karaf@root> config:edit org.ops4j.pax.logging
FuseMQ:karaf@root> config:propset log4j.rootLogger "DEBUG, out, osgi:VmLogAppender"
FuseMQ:karaf@root> config:propappend log4j.appender.stdout.threshold WARN
FuseMQ:karaf@root> config:update

Viewing the Log

Overview

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

Viewing the log in a text editor

The log files are stored as simple text files in InstallDir/data/log. The main log file is karaf.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

Viewing the log with the console

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.

Viewing the log with the administration client

If you do not have a broker running in console mode, you can also use the administration client to invoke the broker's log displaying commands. For example, entering client log:display into a system terminal will display the most recent log entries for the local broker.

Chapter 5. Using JMX

Fuse MQ Enterprise is fully instrumented to provide statistics about its performance using JMX. You can monitor a broker using any JMX aware monitoring tool.

Configuring JMX
Statistics Collected by JMX
Managing the Broker with JMX

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.

Configuring JMX

Revision History

Overview

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://hostname:1099/jmxrmi. 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.

Enabling and disabling

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.

Securing access to JMX

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.

Advanced configuration

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 5.1 describes the configuration properties for controlling a broker's JMX behavior.

Table 5.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 `false` so that the broker uses the container's JMX connection.

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

Example 5.1. Configuring a Broker's JMX Connection

<broker ... >
  ...
  <managementContext>
    <managementContext createMBeanServer="false"
                       createConnector="false" />
  </managementContext>
  ...
</broker>

Statistics Collected by JMX

Broker statistics

Table 5.2 describes the statistics collected for a broker.

Table 5.2. Broker JMX Statistics

Name	Description
BrokerId	Specifies the broker's unique ID.
BrokerName	Specifies the broker's name.
BrokerVersion	Specifies the version of the broker.
DataDirectory	Specifies the pathname of the broker's data directory.
TotalEnqueueCount	Specifies the total number of messages that have been sent to the broker.
TotalDequeueCount	Specifies the number of messages that have been acknowledged on the broker.
TotalConsumerCount	Specifies the number of message consumers subscribed to destinations on the broker.
TotalProducerCount	Specifies the number of message producers active on destinations on the broker.
TotalMessageCount	Specifies the number of unacknowledged messages on the broker.
MemoryLimit	Specifies the memory limit, in bytes, used for holding undelivered messages before paging to temporary storage.
MemoryPercentageUsed	Specifies the percentage of available memory in use.
StoreLimit	Specifies the disk space limit, in bytes, used for persistent messages before producers are blocked.
StorePercentageUsed	Specifies the percentage of the store space in use.
TempLimit	Specifies the disk space limit, in bytes, used for non-persistent messages and temporary data before producers are blocked.
TempPercentageUsed	Specifies the percentage of available temp space in use.

Destination statistics

Table 5.3 describes the statistics collected for a destination.

Table 5.3. Destination JMX Statistics

Name	Description
BlockedProducerWarningInterval	Specifies, in milliseconds, the interval between warnings issued when a producer is blocked from adding messages to the destination.
MemoryLimit	Specifies the memory limit, in bytes, used for holding undelivered messages before paging to temporary storage.
MemoryPercentageUsed	Specifies the percentage of available memory in use.
MaxPageSize	Specifies the maximum number of messages that can be paged into the destination.
CursorFull	Specifies if the cursor has reached its memory limit for paged messages.
CursorMemoryUsage	Specifies, in bytes, the amount of memory the cursor is using.
CursorPercentUsage	Specifies the percentage of the cursor's available memory is in use.
EnqueueCount	Specifies the number of messages that have been sent to the destination.
DequeueCount	Specifies the number of messages that have been acknowledged and removed from the destination.
DispatchCount	Specifies the number of messages that have been delivered to consumers, but not necessarily acknowledged by the consumer.
InFlightCount	Specifies the number of dispatched to, but not acknowledged by, consumers.
ExpiredCount	Specifies the number of messages that have expired in the destination.
ConsumerCount	Specifies the number of consumers that are subscribed to the destination.
QueueSize	Specifies the number of messages in the destination that are waiting to be consumed.
AverageEnqueueTime	Specifies the average amount of time, in milliseconds, that messages sat in the destination before being consumed.
MaxEnqueueTime	Specifies the longest amount of time, in milliseconds, that a message sat in the destination before being consumed.
MinEnqueueTime	Specifies the shortest amount of time, in milliseconds, that a message sat in the destination before being consumed.
MemoryUsagePortion	Specifies the portion of the broker's memory limit used by the destination.
ProducerCount	Specifies the number of producers connected to the destination.

Subscription statistics

Table 5.4 describes the statistics collected for a subscription.

Table 5.4. Connection JMX Statistics

Name	Description
EnqueueCounter	Counts the number of messages that matched the subscription.
DequeueCounter	Counts the number of messages were sent to and acknowledge by the client.
DispatchedQueueSize	Specifies the number of messages dispatched to the client and are awaiting acknowledgement.
DispatchedCounter	Counts the number of messages that have been sent to the client.
MessageCountAwaitingAcknowledge	Specifies the number of messages dispatched to the client and are awaiting acknowledgement.
Active	Specifies if the subscription is active.
PendingQueueSize	Specifies the number of messages pending delivery.
PrefetchSize	Specifies the number of messages to pre-fetch and dispatch to the client.
MaximumPendingMessageLimit	Specifies the maximum number of pending messages allowed.

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

Connector actions

Table 5.6 describes the operations exposed by the MBean for a transport connector.

Table 5.6. Connector MBean Operations

Operation	Description
`void start();`	Starts the transport connector so that it is ready to receive connections from clients.
`void stop();`	Closes the transport connection and disconnects all connected clients.
`int connectionCount();`	Returns the number of open connections using the connector.
`void enableStatistics();`	Enables statistics collection for the connector.
`void resetStatistics();`	Resets the statistics collected for the connector.
`void disableStatistics();`	Deactivates the collection of statistics for the connector.

Network connector actions

Table 5.7 describes the operations exposed by the MBean for a network connector.

Table 5.7. Network Connector MBean Operations

Operation	Description
`void start();`	Starts the network connector so that it is ready to communicate with other brokers in a network of brokers.
`void stop();`	Closes the network connection and disconnects the broker from any brokers that used the network connector to form a network of brokers.

Queue actions

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

Table 5.8. Queue MBean Operations

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

Topic actions

Table 5.9 describes the operations exposed by the MBean for a topic destination.

Table 5.9. Topic MBean Operations

Operation	Description
`CompositeData[] browse();`	Returns all messages in the topic as an array.
`CompositeData[] browse(String selector);`	Returns all messages in the topic that match the selector as an array.
`TabularData browseAsTable(String selector);`	Returns all messages in the topic that match the selector as a table.
`TabularData browseAsTable();`	Returns all messages in the topic as a table.
`void resetStatistics();`	Resets the statistics collected for the queue.
`java.util.List browseMessages(String selector);`	Returns all messages in the topic that match the selector as a list.
`java.util.List browseMessages();`	Returns all messages in the topic as a list.
`String sendTextMessage(String body, String username, String password);`	Send a text message to a secure topic.
`String sendTextMessage(String body);`	Send a text message to a topic.

Subscription actions

Table 5.10 describes the operations exposed by the MBean for a durable subscription.

Table 5.10. Subscription MBean Operations

Operation	Description
`void destroy();`	Destroys the subscription.
`CompositeData[] browse();`	Returns all messages waiting for the subscriber.
`TabularData browseAsTable();`	Returns all messages waiting for the subscriber.
`int cursorSize();`	Returns the number of messages available to be paged in by the cursor.
`boolean doesCursorHaveMessagesBuffered();`	Returns `true` if the cursor has buffered messages to be delivered.
`boolean doesCursorHaveSpace();`	Returns `true` if the cursor has memory space available.
`boolean isMatchingQueue(String queueName);`	Returns `true` if this subscription matches the given queue name.
`boolean isMatchingTopic(String topicName);`	Returns `true` if this subscription matches the given topic name.

Index

A

Active, Subscription statistics

activemq.xml, Editing the configuration template

administration console

port number, Changing the port
securing, Securing the console
url, Accessing the console

AverageEnqueueTime, Destination statistics

B

BlockedProducerWarningInterval, Destination statistics

broker

addConnector, Broker actions

addNetworkConnector, Broker actions

addQueue, Broker actions

addTopic, Broker actions

createDurableSubscriber, Broker actions

deploying

fabric container, Fabric containers
standalone container, Standalone containers

destroyDurableSubscriber, Broker actions

disableStatistics, Broker actions

enableStatistics, Broker actions

gc, Broker actions

reloadLog4jProperties, Broker actions

removeConnector, Broker actions

removeNetworkConnector, Broker actions

removeQueue, Broker actions

removeTopic, Broker actions

resetStatistics, Broker actions

start, Broker actions

stop, Broker actions

stopGracefully, Broker actions

terminateJVM, Broker actions

useJmx, Enabling and disabling

BrokerId, Broker statistics

BrokerName, Broker statistics

BrokerVersion, Broker statistics

C

config shell, Editing the OSGi properties, Standalone containers

config.properties, Overview

configuration

persistent identifier, OSGi PIDs
PID, OSGi PIDs
template, Configuration templates

connector

connectionCount, Connector actions
disableStatistics, Connector actions
enableStatistics, Connector actions
resetStatistics, Connector actions
start, Connector actions
stop, Connector actions

connectorHost, Advanced configuration

connectorPath, Advanced configuration

connectorPort, Advanced configuration

console

config shell, Editing the OSGi properties

ConsumerCount, Destination statistics

createConnector, Advanced configuration

createMBeanServer, Advanced configuration

CursorFull, Destination statistics

CursorMemoryUsage, Destination statistics

CursorPercentUsage, Destination statistics

D

DataDirectory, Broker statistics
DequeueCount, Destination statistics
DequeueCounter, Subscription statistics
DispatchCount, Destination statistics
DispatchedCounter, Subscription statistics
DispatchedQueueSize, Subscription statistics

E

embedded console

disabling, Disabling the embedded console

EnqueueCount, Destination statistics

EnqueueCounter, Subscription statistics

ExpiredCount, Destination statistics

F

fabric

profiles, Profiles
versions, Profiles

fabric shell, Fabric containers

fabric:mq-create, Fabric containers

I

InFlightCount, Destination statistics

J

JMX

disabling, Enabling and disabling
roles, Securing access to JMX

jmxDomainName, Advanced configuration

L

logging

console commands, Viewing the log with the console, Viewing the log with the administration client
viewing as text, Viewing the log in a text editor
viewing in an editor, Viewing the log in a text editor
viewing in the console, Viewing the log with the console
viewing with the admin client, Viewing the log with the administration client

M

managementContext, Advanced configuration

connectorHost, Advanced configuration
connectorPath, Advanced configuration
connectorPort, Advanced configuration
createConnector, Advanced configuration
createMBeanServer, Advanced configuration
jmxDomainName, Advanced configuration
rmiServerPort, Advanced configuration
useMBeanServer, Advanced configuration

MaxEnqueueTime, Destination statistics

MaximumPendingMessageLimit, Subscription statistics

MaxPageSize, Destination statistics

MemoryLimit, Broker statistics, Destination statistics

MemoryPercentageUsed, Broker statistics, Destination statistics

MemoryUsagePortion, Destination statistics

MessageCountAwaitingAcknowledge, Subscription statistics

MinEnqueueTime, Destination statistics

mq-create, Fabric containers

N

network connector

start, Network connector actions
stop, Network connector actions

O

org.apache.karaf.log, Overview

org.ops4j.pax.logging, Overview

org.ops4j.pax.logging.DefaultServiceLog.level, Overview

OSGi configuration

creating, Standalone containers

P

PendingQueueSize, Subscription statistics

persistent identifier, OSGi PIDs

PID, OSGi PIDs

PrefetchSize, Subscription statistics

ProducerCount, Destination statistics

profile

creating, Fabric containers

Q

queue

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

QueueSize, Destination statistics

R

rmiServerPort, Advanced configuration

roles

JMX, Securing access to JMX

routing console

securing, Securing the console

S

SslSelectChannelConnector, Enabling SSL security

standalone broker

configuration template, Editing the configuration template
runtime configuration, Editing the OSGi properties

StoreLimit, Broker statistics

StorePercentageUsed, Broker statistics

subscription

browse, Subscription actions
browseAsTable, Subscription actions
cursorSize, Subscription actions
destory, Subscription actions
doesCursorHaveMessagesBuffered, Subscription actions
doesCursorHaveSpace, Subscription actions
isMatchingQueue, Subscription actions
isMatchingTopic, Subscription actions

T

TempLimit, Broker statistics

TempPercentageUsed, Broker statistics

topic

browse, Topic actions
browseAsTable, Topic actions
browseMessages, Topic actions
resetStatistics, Topic actions
sendTextMessage, Topic actions

TotalConsumerCount, Broker statistics

TotalDequeueCount, Broker statistics

TotalEnqueueCount, Broker statistics

TotalMessageCount, Broker statistics

TotalProducerCount, Broker statistics

U

useJmx, Enabling and disabling
useMBeanServer, Advanced configuration

W

Web console

accessing, Accessing the console
basic authentication, Enabling basic authentication
clusters, Monitoring clusters
port number, Changing the port
roles, Editing user credentials
securing, Securing the console
SSL, Enabling SSL security
user credentials, Editing user credentials

webconsole.jms.url, Configuring Tomcat, Monitoring clusters

webconsole.jmx.password, Configuring Tomcat

webconsole.jmx.url, Configuring Tomcat, Monitoring clusters

webconsole.jmx.user, Configuring Tomcat

	Note
	In the current example, the truststore is actually irrelevant, because clients are not required to send a certificate to the Jetty server.

	Important
	The PID must start with `org.fusesource.mq.fabric.server-`.

	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.