8.5. Broker Configuration

Overview

The examples presented so far have demonstrated how to create brokers with default configuration settings. In practice, you will usually need to customize the broker configurations and this can be done by editing the properties of the corresponding Fabric profiles.

Setting OSGi Config Admin properties

Many of the broker configuration settings can be altered by editing OSGi Config Admin properties (which are organized into collections identified by a persistent ID or PID). For example, consider the broker1 profile created by entering the following fabric:mq-create command:

fabric:mq-create --create-container broker --replicas 1 --network us-west brokerx

The preceding command creates the new profile, mq-broker-default.brokerx, and assigns this profile to the newly created broker1 container.

Note

The new profile gets the name mq-broker-Group.BrokerName by default. If you want the profile to have the same name as the broker (which was the default in JBoss A-MQ version 6.0), you can specify the profile name explicitly using the --profile option.

You can inspect the details of the mq-broker-default.brokerx profile using the fabric:profile-display command, as follows:

JBossFuse:karaf@root> profile-display mq-broker-default.brokerx 
Profile id: mq-broker-default.brokerx
Version   : 1.0
Attributes: 
	    parents: mq-base
Containers:

Container settings
----------------------------

Configuration details
----------------------------
PID: io.fabric8.mq.fabric.server-brokerx
  connectors openwire mqtt amqp stomp
  data ${runtime.data}brokerx
  standby.pool default
  keystore.file profile:keystore.jks
  kind MasterSlave
  keystore.password mca^e.Xg
  broker-name brokerx
  ssl true
  truststore.password mca^e.Xg
  keystore.cn localhost
  keystore.url profile:keystore.jks
  truststore.file profile:truststore.jks
  config profile:ssl-broker.xml
  group default
  network us-west


Other resources
----------------------------
Resource: truststore.jks
Resource: keystore.jks

Associated with the io.fabric8.mq.fabric.server-brokerx PID are a variety of property settings, such as network and group. You can now modify the existing properties or add more properties to this PID to customize the broker configuration.

Modifying basic configuration properties

You can modify the basic configuration properties associated with the io.fabric8.mq.fabric.server-brokerx PID by invoking the fabric:profile-edit command, with the appropriate syntax for modifying PID properties.

For example, to change the value of the network property to us-east, enter the following console command:

profile-edit --pid io.fabric8.mq.fabric.server-brokerx/network=us-east mq-broker-default.brokerx

Customizing the SSL keystore.jks and truststore.jks file

When using a broker with SSL security, it is necessary to replace the default keystore files with your own custom versions. The following JKS resources are stored in the mq-broker-default.brokerx profile when SSL is enabled (which is the default case):

keystore.jks: A Java keystore file containing this broker's own X.509 certificate. The broker uses this certificate to identify itself to other brokers in the network. The password for this file is stored in the io.fabric8.mq.fabric.server-brokerx/keystore.password property.
truststore.jks: A Java truststore file containing one or more Certificate Authority (CA) certificates or other certificates, which are used to verify the certificates presented by other brokers during the SSL handshake. The password for this file is stored in the io.fabric8.mq.fabric.server-brokerx/truststore.password property.

For replacing entire resource files in a profile, the easiest approach to take is to make a git clone of the profile data from the Fabric ensemble server (which also acts as a git server) and then use git to update the profile data. For more details about how to use git in Fabric, see Chapter 16, Configuring with Git.

For example, to customize the SSL settings for the mq-broker-default.brokerx profile, perform the following steps:

If you have not done so already, clone the git repository that stores all of the profile data in your Fabric. Enter a command like the following:
```
git clone -b 1.0 http://Username:Password@localhost:8181/git/fabric
cd fabric
```
Where Username and Password are the credentials of a Fabric user with Administrator role and we assume that you are currently working with profiles in version 1.0 (which corresponds to the git branch named 1.0).
Note
In this example, it is assumed that the fabric is set up to use the git cluster architecture (which is the default) and also that the Fabric server running on localhost is currently the master instance of the git cluster.
The keystore.jks file and the truststore.jks file can be found at the following locations in the git repository:
```
fabric/profiles/mq/broker/default.brokerx.profile/keystore.jks
fabric/profiles/mq/broker/default.brokerx.profile/truststore.jks
```
Copy your custom versions of the keystore.jks file and truststore.jks file to these locations, over-writing the default versions of these files.
You also need to modify the corresponding passwords for the keystore and truststore. To modify the passwords, edit the following file in a text editor:
```
fabric/profiles/mq/broker/default.brokerx.profile/io.fabric8.mq.fabric.server-brokerx.properties
```
Modify the keystore.password and truststore.password settings in this file, to specify the correct password values for your custom JKS files.
When you are finished modifying the profile configuration, commit and push the changes back to the Fabric server using git, as follows:
```
git commit -a -m "Put a description of your changes here!"
git push
```
For these SSL configuration changes to take effect, a restart of the affected broker (or brokers) is required. For example, assuming that the modified profile is deployed on the broker container, you would restart the broker container as follows:
```
fabric:container-stop broker
fabric:container-start broker
```

Customizing the broker configuration file

Another important aspect of broker configuration is the ActiveMQ broker configuration file, which is specified as a Spring XML file. There are two alternative versions of the broker configuration file: ssl-broker.xml, for an SSL-enabled broker; and broker.xml, for a non-SSL-enabled broker.

If you want to customize the broker configuration, it is recommended that you create a copy of the broker configuration file in your broker's own profile (instead of inheriting the broker configuration from the mq-base parent profile). The easiest way to make this kind of change is to use a git repository of profile data that has been cloned from a Fabric ensemble server.

For example, to customize the broker configuration for the mq-broker-default.brokerx profile, perform the following steps:

It is assumed that you have already cloned the git repository of profile data from the Fabric ensemble server (see the section called “Customizing the SSL keystore.jks and truststore.jks file”). Make sure that you have checked out the branch corresponding to the profile version that you want to edit (which is assumed to be 1.0 here). It is also a good idea to do a git pull to ensure that your local git repository is up-to-date. In your git repository, enter the following git commands:
```
git checkout 1.0
git pull
```
The default broker configuration files are stored at the following location in the git repository:
```
fabric/profiles/mq/base.profile/ssl-broker.xml
fabric/profiles/mq/base.profile/broker.xml
```
Depending on whether your broker is configured with SSL or not, you should copy either the ssl-broker.xml file or the broker.xml file into your broker's profile. For example, assuming that your broker uses the mq-broker-default.brokerx profile and is configured to use SSL, you would copy the broker configuration as follows:
```
cp fabric/profiles/mq/base.profile/ssl-broker.xml fabric/profiles/mq/broker/default.brokerx.profile/
```
You can now edit the copy of the broker configuration file, customizing the broker's Spring XML configuration as required.
When you are finished modifying the broker configuration, commit and push the changes back to the Fabric server using git, as follows:
```
git commit -a -m "Put a description of your changes here!"
git push
```
For the configuration changes to take effect, a restart of the affected broker (or brokers) is required. For example, assuming that the modified profile is deployed on the broker container, you would restart the broker container as follows:
```
fabric:container-stop broker
fabric:container-start broker
```

Additional broker configuration templates in mq-base

If you like, you can add extra broker configurations to the mq-base profile, which can then be used as templates for creating new brokers with the fabric:mq-create command. Additional template configurations must be added to the following location in the git repository:

fabric/profiles/mq/base.profile/

You can then reference one of the templates by supplying the --config option to the fabric:mq-create command.

For example, given that a new broker configuration, mybrokertemplate.xml, has just been installed:

fabric/profiles/mq/base.profile/mybrokertemplate.xml

You could use this custom mybrokertemplate.xml configuration template by invoking the fabric:mq-create command with the --config option, as follows:

fabric:mq-create --config mybrokertemplate.xml brokerx

The --config option assumes that the configuration file is stored in the current version of the mq-base profile, so you need to specify only the file name (that is, the full ZooKeeper path is not required).

Setting network connector properties

You can specify additional configuration for network connectors, where the property names have the form network.NetworkPropName. For example, to add the setting, network.bridgeTempDestinations=false, to the PID for brokerx (which has the profile name, mq-broker-default.brokerx), enter the following console command:

profile-edit --pid io.fabric8.mq.fabric.server-brokerx/network.bridgeTempDestinations=false mq-broker-default.brokerx

The deployed broker dynamically detects the change to this property and updates the network connector on the fly.

Network connector properties by reflection

Fabric uses reflection to set network connector properties. That is, any PID property of the form network.OptionName can be used to set the corresponding OptionName property on the org.apache.activemq.network.NetworkBridgeConfiguration class. In particular, this implies you can set any of the following network.OptionName properties:

Property	Default	Description
`name`	`bridge`	Name of the network - for more than one network connector between the same two brokers, use different names
`userName`	None	Username for logging on to the remote broker port, if authentication is enabled.
`password`	None	Password for logging on to the remote broker port, if authentication is enabled.
`dynamicOnly`	`false`	If `true`, only activate a networked durable subscription when a corresponding durable subscription reactivates, by default they are activated on start-up.
`dispatchAsync`	`true`	Determines how the network bridge sends messages to the local broker. If `true`, the network bridge sends messages asynchronously.
`decreaseNetworkConsumerPriority`	`false`	If `true`, starting at priority `-5`, decrease the priority for dispatching to a network Queue consumer the further away it is (in network hops) from the producer. If `false`, all network consumers use same default priority (that is, `0`) as local consumers.
`consumerPriorityBase`	`-5`	Sets the starting priority for consumers. This base value will be decremented by the length of the broker path when `decreaseNetworkConsumerPriority` is set.
`networkTTL`	`1`	The number of brokers in the network that messages and subscriptions can pass through (sets both `messageTTL` and `consumerTTL`)
`messageTTL`	`1`	The number of brokers in the network that messages can pass through.
`consumerTTL`	`1`	The number of brokers in the network that subscriptions can pass through (keep to 1 in a mesh).
`conduitSubscriptions`	`true`	Multiple consumers subscribing to the same destination are treated as one consumer by the network.
`duplex`	`false`	If `true`, a network connection is used both to produce and to consume messages. This is useful for hub and spoke scenarios, when the hub is behind a firewall, and so on.
`prefetchSize`	`1000`	Sets the prefetch size on the network connector's consumer. It must be greater than `0`, because network consumers do not poll for messages
`suppressDuplicateQueueSubscriptions`	`false`	If `true`, duplicate subscriptions in the network that arise from network intermediaries are suppressed. For example, consider brokers `A`, `B`, and `C`, networked using multicast discovery. A consumer on `A` gives rise to a networked consumer on `B` and `C`. In addition, `C` networks to `B` (based on the network consumer from `A`) and `B` networks to `C`. When `true`, the network bridges between `C` and `B` (being duplicates of their existing network subscriptions to `A`) will be suppressed. Reducing the routing choices in this way provides determinism when producers or consumers migrate across the network as the potential for dead routes (stuck messages) are eliminated. The `networkTTL` value needs to match or exceed the broker count to require this intervention.
`suppressDuplicateTopicSubscriptions`	`true`	If `true`, duplicate network topic subscriptions (in a cyclic network) are suppressed.
`bridgeTempDestinations`	`true`	Whether to broadcast advisory messages for temporary destinations created in the network of brokers. Temporary destinations are typically created for request-reply messages. Broadcasting the information about temp destinations is turned on by default, so that consumers of a request-reply message can be connected to another broker in the network and still send back the reply on the temporary destination specified in the `JMSReplyTo` header. In an application scenario where most or all of the messages use the request-reply pattern, this generates additional traffic on the broker network, because every message typically sets a unique `JMSReplyTo` address (which causes a new temp destination to be created and broadcasted with an advisory message in the network of brokers). If you disable this feature, this network traffic can be reduced, but in this case the producers and consumers of a request-reply message need to be connected to the same broker. Remote consumers (that is, connected through another broker in your network) will not be able to send the reply message, but instead will raise a `temp destination does not exist` exception.
`alwaysSyncSend`	`false`	If `true`, non-persistent messages are sent to the remote broker using request/reply semantics instead of oneway message semantics. This setting affects both persistent and non-persistent messages the same way.
`staticBridge`	`false`	If `true`, the broker does not respond dynamically to new consumers. It uses only `staticallyIncludedDestinations` to create demand subscriptions.
`useCompression`	`false`	Compresses the message body when sending it over the network.
`advisoryForFailedForward`	`false`	If `true`, send an advisory message when the broker fails to forward the message to the temporary destination across the bridge.
`useBrokerNamesAsIdSeed`	`true`	Add the broker name as a prefix to connections and consumers created by the network bridge. It helps with visibility.
`gcDestinationViews`	`true`	If `true`, remove any MBeans for destinations that have not been used for a while.
`gcSweepTime`	`60000`	The period of inactivity in milliseconds, after which we remove MBeans.
`checkDuplicateMessagesOnDuplex`	`false`	If `true`, check for duplicates on the duplex connection.

8.5. Broker Configuration

Overview

Setting OSGi Config Admin properties

Modifying basic configuration properties

Customizing the SSL keystore.jks and truststore.jks file

Customizing the broker configuration file

Additional broker configuration templates in mq-base

Setting network connector properties

Network connector properties by reflection

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links