Este conteúdo não está disponível no idioma selecionado.
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: broker
Container settings
----------------------------
Configuration details
----------------------------
PID: io.fabric8.mq.fabric.server-brokerx
replicas 1
standby.pool default
broker-name brokerx
keystore.password JA7GNMZV
data ${runtime.data}brokerx
keystore.file profile:keystore.jks
ssl true
kind MasterSlave
truststore.file profile:truststore.jks
keystore.cn localhost
connectors openwire mqtt amqp stomp
truststore.password JA7GNMZV
keystore.url profile:keystore.jks
config profile:ssl-broker.xml
group default
network us-west
Other resources
----------------------------
Resource: keystore.jks
Resource: truststore.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.passwordproperty. 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.passwordproperty.
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
WhereUsernameandPasswordare the credentials of a Fabric user withAdministratorrole and we assume that you are currently working with profiles in version1.0(which corresponds to the git branch named1.0).NoteIn 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 onlocalhostis currently the master instance of the git cluster. - The
keystore.jksfile and thetruststore.jksfile 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 thekeystore.jksfile andtruststore.jksfile 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 thekeystore.passwordandtruststore.passwordsettings 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
brokercontainer, you would restart thebrokercontainer 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.0here). 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 thessl-broker.xmlfile or thebroker.xmlfile into your broker's profile. For example, assuming that your broker uses themq-broker-default.brokerxprofile 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
brokercontainer, you would restart thebrokercontainer 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. |
