Configuring AMQ Broker

1. The broker currently does not support virtual hosting, which means the host header in CONNECT frames are ignored.
2. Message acknowledgements are not transactional. The ACK frame cannot be part of a transaction, and it is ignored if its transaction header is set).

Procedure

1. Open the configuration file BROKER_INSTANCE_DIR/etc/broker.xml
2. Set the stompEnableMessageId parameter to true for the acceptor used for STOMP connections, as shown in the following example:

Procedure

1. Open the configuration file BROKER_INSTANCE_DIR/etc/broker.xml
2. Add the connectionTTL parameter to URI of the acceptor used for STOMP connections, as shown in the following example:

Procedure

1. Open the configuration file BROKER_INSTANCE_DIR/etc/broker.xml
2. Add the connection-ttl-override attribute and provide a value in milliseconds for the new default. It belongs inside the <core> stanza, as below.

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. Add a <wildcard-addresses> section to the configuration, as in the example below.

   <configuration>
     <core>
       ...
       <wildcard-addresses> //
         <enabled>true</enabled> //
         <delimiter>,</delimiter> //
         <any-words>@</any-words> //
         <single-word>$</single-word>
       </wildcard-addresses>
       ...
     </core>
   </configuration>

   enabled

   When set to true, instruct the broker to use your custom settings.

   delimiter

   Provide a custom character to use as the delimiter instead of the default, which is ..

   any-words

   The character provided as the value for any-words is used to mean 'match any sequence of zero or more words' and will replace the default #. Use this character at the end of your expression.

   single-word

   The character provided as the value for single-word is used to mean 'match a single word' and will replaced the default *. Use this character anywhere within your expression.

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. Wrap an anycast configuration element around the chosen queue element of an address. Ensure that the values of the name attribute for both the address and queue elements are the same. For example:

   <configuration ...>
     <core ...>
       ...
       <address name="my.anycast.destination">
         <anycast>
           <queue name="my.anycast.destination"/>
         </anycast>
       </address>
     </core>
   </configuration>

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. Wrap an anycast configuration element around the queue elements in the address element. For example:

   <configuration ...>
     <core ...>
       ...
       <address name="my.anycast.destination">
         <anycast>
           <queue name="q1"/>
           <queue name="q2"/>
         </anycast>
       </address>
     </core>
   </configuration>

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. Add the durable configuration element to a chosen queue. Set a value of true.

   <configuration ...>
     <core ...>
       ...
       <address name="my.durable.address">
         <multicast>
           <queue name="q1">
             <durable>true</durable>
           </queue>
         </multicast>
       </address>
     </core>
   </configuration>

   Note

   Because queues are durable by default, including the durable element and setting the value to true is not strictly necessary to create a durable queue. However, explicitly including the element enables you to later change the behavior of the queue to non-durable, if necessary.

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. Add the durable configuration element to each chosen queue. Set a value of true.

   <configuration ...>
     <core ...>
       ...
       <address name="my.non.shared.durable.address">
         <multicast>
           <queue name="orders1">
             <durable>true</durable>
           </queue>
           <queue name="orders2">
             <durable>true</durable>
           </queue>
         </multicast>
       </address>
     </core>
   </configuration>

   Note

   Because queues are durable by default, including the durable element and setting the value to true is not strictly necessary to create a durable queue. However, explicitly including the element enables you to later change the behavior of the queue to non-durable, if necessary.

3. Add the max-consumers attribute to each chosen queue. Set a value of 1.

   <configuration ...>
     <core ...>
       ...
       <address name="my.non.shared.durable.address">
         <multicast>
           <queue name="orders1" max-consumers="1">
             <durable>true</durable>
           </queue>
           <queue name="orders2" max-consumers="1">
             <durable>true</durable>
           </queue>
         </multicast>
       </address>
     </core>
   </configuration>

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. Add the purge-on-no-consumers attribute to each chosen queue. Set a value of true.

   <configuration ...>
     <core ...>
       ...
       <address name="my.non.durable.address">
           <multicast>
               <queue name="orders1" purge-on-no-consumers="true"/>
           </multicast>
       </address>
     </core>
   </configuration>

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. Configure an address-setting for automatic creation and deletion. The following example uses all of the configuration elements mentioned in the previous table.

   <configuration ...>
    <core ...>
     ...
     <address-settings>
       <address-setting match="activemq.#">
         <auto-create-addresses>true</auto-create-addresses>
         <auto-delete-addresses>true</auto-delete-addresses>
         <auto-create-queues>true</auto-create-queues>
         <auto-delete-queues>true</auto-delete-queues>
         <default-address-routing-type>ANYCAST</default-address-routing-type>
       </address-setting>
     </address-settings>
     ...
    </core>
   </configuration>

   address-setting

   The configuration of the address-setting element is applied to any address or queue that matches the wildcard address activemq.#.

   auto-create-addresses

   When a client requests to connect to an address that does not yet exist, the broker creates the address.

   auto-delete-addresses

   An automatically created address is deleted when it no longer has any queues associated with it.

   auto-create-queues

   When a client requests to connect to a queue that does not yet exist, the broker creates the queue.

   auto-delete-queues

   An automatically created queue is deleted when it no longer has any consumers or messages.

   default-address-routing-type

   If the client does not specify a routing type when connecting, the broker uses ANYCAST when delivering messages to an address. The default value is MULTICAST.

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. For a given queue, add the last-value-key key and specify a custom value. For example:

   <address name="my.address">
       <multicast>
           <queue name="prices1" last-value-key="stock_ticker"/>
       </multicast>
   </address>

3. Alternatively, you can configure a last value queue that uses the default last value key name of _AMQ_LVQ_NAME. To do this, add the last-value key to a given queue. Set the value to true. For example:

   <address name="my.address">
       <multicast>
           <queue name="prices1" last-value="true"/>
       </multicast>
   </address>

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. In the address-setting element, for a matching address, add default-last-value-key. Specify a custom value. For example:

   <address-setting match="lastValue">
      <default-last-value-key>stock_ticker</default-last-value-key>
   </address-setting>

   Based on the preceding configuration, all queues associated with the lastValue address use a last value key of stock_ticker. By default, the value of default-last-value-key is not set.

3. To configure last value queues for a set of addresses, you can specify an address wildcard. For example:

   <address-setting match="lastValue.*">
      <default-last-value-key>stock_ticker</default-last-value-key>
   </address-setting>

4. Alternatively, you can configure all queues associated with an address or set of addresses to use the default last value key name of _AMQ_LVQ_NAME. To do this, add default-last-value-queue instead of default-last-value-key. Set the value to true. For example:

   <address-setting match="lastValue">
      <default-last-value-queue>true</default-last-value-queue>
   </address-setting>

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. If you previously configured a queue individually as a last value queue, add the non-destructive key. Set the value to true. For example:

   <address name="my.address">
      <multicast>
         <queue name="orders1" last-value-key="stock_ticker" non-destructive="true" />
      </multicast>
   </address>

3. If you previously configured an address or set of addresses for last value queues, add the default-non-destructive key. Set the value to true. For example:

   <address-setting match="lastValue">
      <default-last-value-key>stock_ticker </default-last-value-key>
      <default-non-destructive>true</default-non-destructive>
   </address-setting>

   Note

   By default, the value of default-non-destructive is false.

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. In the core element, set the message-expiry-scan-period to specify how frequently the broker scans for expired messages.

   <configuration ...>
      <core ...>
         ...
         <message-expiry-scan-period>1000</message-expiry-scan-period>
         ...

   Based on the preceding configuration, the broker scans queues for expired messages every 1000 milliseconds.

3. In the address-setting element for a matching address or set of addresses, specify an expiry address. Also, set a message expiration time. For example:

   <configuration ...>
      <core ...>
         ...
         <address-settings>
            ...
            <address-setting match="stocks">
               ...
               <expiry-address>ExpiryAddress</expiry-address>
               <expiry-delay>10</expiry-delay>
               ...
            </address-setting>
            ...
         <address-settings>
   <configuration ...>

   expiry-address

   Expiry address for the matching address or addresses. In the preceding example, the broker sends expired messages for the stocks address to an expiry address called ExpiryAddress.

   expiry-delay

   Expiration time, in milliseconds, that the broker applies to messages that are using the default expiration time. By default, messages have an expiration time of 0, meaning that they don’t expire. For messages with an expiration time greater than the default, expiry-delay has no effect.

   For example, suppose you set expiry-delay on an address to 10, as shown in the preceding example. If a message with the default expiration time of 0 arrives to a queue at this address, then the broker changes the expiration time of the message from 0 to 10. However, if another message that is using an expiration time of 20 arrives, then its expiration time is unchanged. If you set expiry-delay to -1, this feature is disabled. By default, expiry-delay is set to -1.

4. Alternatively, instead of specifying a value for expiry-delay, you can specify minimum and maximum expiry delay values. For example:

   <configuration ...>
      <core ...>
         ...
         <address-settings>
            ...
            <address-setting match="stocks">
               ...
               <expiry-address>ExpiryAddress</expiry-address>
               <min-expiry-delay>10</min-expiry-delay>
               <max-expiry-delay>100</max-expiry-delay>
               ...
            </address-setting>
            ...
         <address-settings>
   <configuration ...>

   min-expiry-delay

   Minimum expiration time, in milliseconds, that the broker applies to messages.

   max-expiry-delay

   Maximum expiration time, in milliseconds, that the broker applies to messages.

   The broker applies the values of min-expiry-delay and max-expiry-delay as follows:

   • For a message with the default expiration time of 0, the broker sets the expiration time to the specified value of max-expiry-delay. If you have not specified a value for max-expiry-delay, the broker sets the expiration time to the specified value of min-expiry-delay. If you have not specified a value for min-expiry-delay, the broker does not change the expiration time of the message.
   • For a message with an expiration time above the value of max-expiry-delay, the broker sets the expiration time to the specified value of max-expiry-delay.
   • For a message with an expiration time below the value of min-expiry-delay, the broker sets the expiration time to the specified value of min-expiry-delay.
   • For a message with an expiration between the values of min-expiry-delay and max-expiry-delay, the broker does not change the expiration time of the message.
   • If you specify a value for expiry-delay (that is, other than the default value of -1), this overrides any values that you specify for min-expiry-delay and max-expiry-delay.
   • The default value for both min-expiry-delay and max-expiry-delay is -1 (that is, disabled).

5. In the addresses element of your configuration file, configure the address previously specified for expiry-address. Define a queue at this address. For example:

   <addresses>
       ...
       <address name="ExpiryAddress">
           <anycast>
               <queue name="ExpiryQueue"/>
           </anycast>
       </address>
       ...
   </addresses>

   The preceding example configuration associates an expiry queue, ExpiryQueue, with the expiry address, ExpiryAddress.

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. Locate the <address-setting> element that you previously added to the configuration file to define an expiry address for a matching address or set of addresses. For example:

   <configuration ...>
   
      <core ...>
         ...
         <address-settings>
            ...
            <address-setting match="stocks">
               ...
               <expiry-address>ExpiryAddress</expiry-address>
               ...
            </address-setting>
            ...
         <address-settings>
   <configuration ...>

3. In the <address-setting> element, add configuration items that instruct the broker to automatically create expiry resources (that is, addresses and queues) and how to name these resources. For example:

   <configuration ...>
      <core ...>
         ...
         <address-settings>
            ...
            <address-setting match="stocks">
               ...
               <expiry-address>ExpiryAddress</expiry-address>
               <auto-create-expiry-resources>true</auto-create-expiry-resources>
               <expiry-queue-prefix>EXP.</expiry-queue-prefix>
               <expiry-queue-suffix></expiry-queue-suffix>
               ...
            </address-setting>
            ...
         <address-settings>
   <configuration ...>

   auto-create-expiry-resources

   Specifies whether the broker automatically creates an expiry address and queue to receive expired messages. The default value is false.

   If the parameter value is set to true, the broker automatically creates an <address> element that defines an expiry address and an associated expiry queue. The name value of the automatically-created <address> element matches the name value specified for <expiry-address>.

   The automatically-created expiry queue has the multicast routing type. By default, the broker names the expiry queue to match the address to which expired messages were originally sent, for example, stocks.

   The broker also defines a filter for the expiry queue that uses the _AMQ_ORIG_ADDRESS property. This filter ensures that the expiry queue receives only messages sent to the corresponding original address.

   expiry-queue-prefix

   Prefix that the broker applies to the name of the automatically-created expiry queue. The default value is EXP.

   When you define a prefix value or keep the default value, the name of the expiry queue is a concatenation of the prefix and the original address, for example, EXP.stocks.

   expiry-queue-suffix

   Suffix that the broker applies to the name of an automatically-created expiry queue. The default value is not defined (that is, the broker applies no suffix).

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. In an <address-setting> element that matches your queue name(s), set values for the dead letter address name and the maximum number of delivery attempts. For example:

   <configuration ...>
      <core ...>
         ...
         <address-settings>
            ...
            <address-setting match="exampleQueue">
               <dead-letter-address>DLA</dead-letter-address>
               <max-delivery-attempts>3</max-delivery-attempts>
            </address-setting>
         ...
         <address-settings>
   <configuration ...>

   match

   Address to which the broker applies the configuration in this address-setting section. You can specify a wildcard expression for the match attribute of the <address-setting> element. Using a wildcard expression is useful if you want to associate the dead letter settings configured in the <address-setting> element with a matching set of addresses.

   dead-letter-address

   Name of the dead letter address. In this example, the broker moves undelivered messages from the queue exampleQueue to the dead letter address, DLA.

   max-delivery-attempts

   Maximum number of delivery attempts made by the broker before it moves an undelivered message to the configured dead letter address. In this example, the broker moves undelivered messages to the dead letter address after three unsuccessful delivery attempts. The default value is 10. If you want the broker to make an infinite number of redelivery attempts, specify a value of -1.

3. In the addresses section, add an address element for the dead letter address, DLA. To associate a dead letter queue with the dead letter address, specify a name value for queue. For example:

   <configuration ...>
      <core ...>
         ...
         <addresses>
            <address name="DLA">
               <anycast>
                  <queue name="DLQ" />
               </anycast>
            </address>
         ...
         </addresses>
      </core>
   </configuration>

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. Locate the <address-setting> element that you previously added to define a dead letter address for a matching queue or set of queues. For example:

   <configuration ...>
      <core ...>
         ...
         <address-settings>
            ...
            <address-setting match="exampleQueue">
               <dead-letter-address>DLA</dead-letter-address>
               <max-delivery-attempts>3</max-delivery-attempts>
            </address-setting>
         ...
         <address-settings>
   <configuration ...>

3. In the <address-setting> element, add configuration items that instruct the broker to automatically create dead letter resources (that is, addresses and queues) and how to name these resources. For example:

   <configuration ...>
      <core ...>
         ...
         <address-settings>
            ...
            <address-setting match="exampleQueue">
               <dead-letter-address>DLA</dead-letter-address>
               <max-delivery-attempts>3</max-delivery-attempts>
               <auto-create-dead-letter-resources>true</auto-create-dead-letter-resources>
               <dead-letter-queue-prefix>DLQ.</dead-letter-queue-prefix>
               <dead-letter-queue-suffix></dead-letter-queue-suffix>
            </address-setting>
         ...
         <address-settings>
   <configuration ...>

   auto-create-dead-letter-resources

   Specifies whether the broker automatically creates a dead letter address and queue to receive undelivered messages. The default value is false.

   If auto-create-dead-letter-resources is set to true, the broker automatically creates an <address> element that defines a dead letter address and an associated dead letter queue. The name of the automatically-created <address> element matches the name value that you specify for <dead-letter-address>.

   The dead letter queue that the broker defines in the automatically-created <address> element has the multicast routing type . By default, the broker names the dead letter queue to match the original address of the undelivered message, for example, stocks.

   The broker also defines a filter for the dead letter queue that uses the _AMQ_ORIG_ADDRESS property. This filter ensures that the dead letter queue receives only messages sent to the corresponding original address.

   dead-letter-queue-prefix

   Prefix that the broker applies to the name of an automatically-created dead letter queue. The default value is DLQ.

   When you define a prefix value or keep the default value, the name of the dead letter queue is a concatenation of the prefix and the original address, for example, DLQ.stocks.

   dead-letter-queue-suffix

   Suffix that the broker applies to an automatically-created dead letter queue. The default value is not defined (that is, the broker applies no suffix).

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. For a given queue, add the exclusive key. Set the value to true.

   <configuration ...>
     <core ...>
       ...
       <address name="my.address">
         <multicast>
           <queue name="orders1" exclusive="true"/>
         </multicast>
       </address>
     </core>
   </configuration>

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. In the address-setting element, for a matching address, add the default-exclusive-queue key. Set the value to true.

   <address-setting match="myAddress">
       <default-exclusive-queue>true</default-exclusive-queue>
   </address-setting>

   Based on the preceding configuration, all queues associated with the myAddress address are exclusive. By default, the value of default-exclusive-queue is false.

3. To configure exclusive queues for a set of addresses, you can specify an address wildcard. For example:

   <address-setting match="myAddress.*">
       <default-exclusive-queue>true</default-exclusive-queue>
   </address-setting>

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. To define a default ring size for all queues on matching addresses that don’t have an explicit ring size set, specify a value for default-ring-size in the address-setting element. For example:

   <address-settings>
      <address-setting match="ring.#">
         <default-ring-size>3</default-ring-size>
      </address-setting>
   </address-settings>

   The default-ring-size parameter is especially useful for defining the default size of auto-created queues. The default value of default-ring-size is -1 (that is, no size limit).

3. To define a ring size on a specific queue, add the ring-size key to the queue element. Specify a value. For example:

   <addresses>
      <address name="myRing">
         <anycast>
            <queue name="myRing" ring-size="5" />
         </anycast>
      </address>
   </addresses>

1. A producer sends three messages to a ring queue configured with ring-size="3".

2. All messages are immediately dispatched to a consumer.

   At this point, messageCount= 3 and deliveringCount= 3.

3. The producer sends another message to the queue. The message is then dispatched to the consumer.

   Now, messageCount = 4 and deliveringCount = 4. The message count of 4 is greater than the configured ring size of 3. However, the broker is obliged to allow this situation because it cannot remove the in-delivery messages from the queue.

4. Now, suppose that the consumer is closed without acknowledging any of the messages.

   In this case, the four in-delivery, unacknowledged messages are canceled back to the broker and added to the head of the queue in the reverse order from which they were consumed. This action puts the queue over its configured ring size. Because a ring queue prefers messages at the tail of the queue over messages at the head, the queue discards the first message sent by the producer, because this was the last message added back to the head of the queue. Transaction or core session rollbacks are treated in the same way.

1. At 12:00, a producer sends a message, A, to a ring queue configured with ring-size="3". The message is scheduled for 12:05.

   At this point, messageCount= 1 and scheduledCount= 1.

2. At 12:01, producer sends message B to the same ring queue.

   Now, messageCount= 2 and scheduledCount= 1.

3. At 12:02, producer sends message C to the same ring queue.

   Now, messageCount= 3 and scheduledCount= 1.

4. At 12:03, producer sends message D to the same ring queue.

   Now, messageCount= 4 and scheduledCount= 1.

   The message count for the queue is now 4, one greater than the configured ring size of 3. However, the scheduled message is not technically on the queue yet (that is, it is on the broker and scheduled to be put on the queue). At the scheduled delivery time of 12:05, the broker puts the message on the head of the queue. However, since the ring queue has already reached its configured size, the scheduled message A is immediately removed.

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. Add a new <federations> element that includes a <federation> element. For example:

   <federations>
     <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
     </federation>
   </federations>

   name

   Name of the federation configuration. In this example, the name corresponds to the name of the local broker.

   user

   Shared user name for connection to the upstream brokers.

   password

   Shared password for connection to the upstream brokers.

   Note

   If user and password credentials differ for remote brokers, you can separately specify credentials for those brokers when you add them to the configuration. This is described later in this procedure.

3. Within the federation element, add an <address-policy> element. For example:

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">
           </address-policy>
   
       </federation>
   </federations>

   name

   Name of the address policy. All address policies that are configured on the broker must have unique names.

   auto-delete

   During address federation, the local broker dynamically creates a durable queue at the remote address. The value of the auto-delete property specifies whether the remote queue should be deleted once the local broker disconnects and the values of the auto-delete-delay and auto-delete-message-count properties have also been reached. This is a useful option if you want to automate the cleanup of dynamically-created queues. It is also a useful option if you want to prevent a buildup of messages on a remote broker if the local broker is disconnected for a long time. However, you might set this option to false if you want messages to always remain queued for the local broker while it is disconnected, avoiding message loss on the local broker.

   auto-delete-delay

   After the local broker has disconnected, the value of this property specifies the amount of time, in milliseconds, before dynamically-created remote queues are eligible to be automatically deleted.

   auto-delete-message-count

   After the local broker has been disconnected, the value of this property specifies the maximum number of messages that can still be in a dynamically-created remote queue before that queue is eligible to be automatically deleted.

   enable-divert-bindings

   Setting this property to true enables divert bindings to be listened-to for demand. If there is a divert binding with an address that matches the included addresses for the address policy, then any queue bindings that match the forwarding address of the divert will create demand. The default value is false.

   max-hops

   Maximum number of hops that a message can make during federation. Particular topologies require specific values for this property. To learn more about these requirements, see Section 4.21.2, “Common topologies for address federation”.

   transformer-ref

   Name of a transformer configuration. You might add a transformer configuration if you want to transform messages during federated message transmission. Transformer configuration is described later in this procedure.

4. Within the <address-policy> element, add address-matching patterns to include and exclude addresses from the address policy. For example:

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">
   
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-policy>
   
       </federation>
   </federations>

   include

   The value of the address-match property of this element specifies addresses to include in the address policy. You can specify an exact address, for example, queue.bbc.new or queue.usatoday. Or, you can use a wildcard expression to specify a matching set of addresses. In the preceding example, the address policy also includes all address names that start with the string queue.news.

   exclude

   The value of the address-match property of this element specifies addresses to exclude from the address policy. You can specify an exact address name or use a wildcard expression to specify a matching set of addresses. In the preceding example, the address policy excludes all address names that start with the string queue.news.sport.

5. (Optional) Within the federation element, add a transformer element to reference a custom transformer implementation. For example:

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">
   
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-policy>
   
           <transformer name="news-transformer">
               <class-name>org.foo.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
   </federations>

   name

   Name of the transformer configuration. This name must be unique on the local broker. This is the name that you specify as a value for the transformer-ref property of the address policy.

   class-name

   Name of a user-defined class that implements the org.apache.activemq.artemis.core.server.transformer.Transformer interface.

   The transformer’s transform() method is invoked with the message before the message is transmitted. This enables you to transform the message header or body before it is federated.

   property

   Used to hold key-value pairs for specific transformer configuration.

6. Within the federation element, add one or more upstream elements. Each upstream element defines a connection to a remote broker and the policies to apply to that connection. For example:

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <upstream name="eu-east-1">
               <static-connectors>
                   <connector-ref>eu-east-connector1</connector-ref>
               </static-connectors>
               <policy ref="news-address-federation"/>
           </upstream>
   
           <upstream name="eu-west-1" >
               <static-connectors>
                   <connector-ref>eu-west-connector1</connector-ref>
               </static-connectors>
               <policy ref="news-address-federation"/>
           </upstream>
   
           <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer">
   
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-policy>
   
           <transformer name="news-transformer">
               <class-name>org.foo.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
   </federations>

   static-connectors

   Contains a list of connector-ref elements that reference connector elements that are defined elsewhere in the broker.xml configuration file of the local broker. A connector defines what transport (TCP, SSL, HTTP, and so on) and server connection parameters (host, port, and so on) to use for outgoing connections. The next step of this procedure shows how to add the connectors that are referenced in the static-connectors element.

   policy-ref

   Name of the address policy configured on the downstream broker that is applied to the upstream broker.

   The additional options that you can specify for an upstream element are described below:

   name

   Name of the upstream broker configuration. In this example, the names correspond to upstream brokers called eu-east-1 and eu-west-1.

   user

   User name to use when creating the connection to the upstream broker. If not specified, the shared user name that is specified in the configuration of the federation element is used.

   password

   Password to use when creating the connection to the upstream broker. If not specified, the shared password that is specified in the configuration of the federation element is used.

   call-failover-timeout

   Similar to call-timeout, but used when a call is made during a failover attempt. The default value is -1, which means that the timeout is disabled.

   call-timeout

   Time, in milliseconds, that a federation connection waits for a reply from a remote broker when it transmits a packet that is a blocking call. If this time elapses, the connection throws an exception. The default value is 30000.

   check-period

   Period, in milliseconds, between consecutive “keep-alive” messages that the local broker sends to a remote broker to check the health of the federation connection. If the federation connection is healthy, the remote broker responds to each keep-alive message. If the connection is unhealthy, when the downstream broker fails to receive a response from the upstream broker, a mechanism called a circuit breaker is used to block federated consumers. See the description of the circuit-breaker-timeout parameter for more information. The default value of the check-period parameter is 30000.

   circuit-breaker-timeout

   A single connection between a downstream and upstream broker might be shared by many federated queue and address consumers. In the event that the connection between the brokers is lost, each federated consumer might try to reconnect at the same time. To avoid this, a mechanism called a circuit breaker blocks the consumers. When the specified timeout value elapses, the circuit breaker re-tries the connection. If successful, consumers are unblocked. Otherwise, the circuit breaker is applied again.

   connection-ttl

   Time, in milliseconds, that a federation connection stays alive if it stops receiving messages from the remote broker. The default value is 60000.

   discovery-group-ref

   As an alternative to defining static connectors for connections to upstream brokers, this element can be used to specify a discovery group that is already configured elsewhere in the broker.xml configuration file. Specifically, you specify an existing discovery group as a value for the discovery-group-name property of this element. For more information about discovery groups, see Section 16.1.5, “Broker discovery methods”.

   ha

   Specifies whether high availability is enabled for the connection to the upstream broker. If the value of this parameter is set to true, the local broker can connect to any available broker in an upstream cluster and automatically fails over to a backup broker if the live upstream broker shuts down. The default value is false.

   initial-connect-attempts

   Number of initial attempts that the downstream broker will make to connect to the upstream broker. If this value is reached without a connection being established, the upstream broker is considered permanently offline. The downstream broker no longer routes messages to the upstream broker. The default value is -1, which means that there is no limit.

   max-retry-interval

   Maximum time, in milliseconds, between subsequent reconnection attempts when connection to the remote broker fails. The default value is 2000.

   reconnect-attempts

   Number of times that the downstream broker will try to reconnect to the upstream broker if the connection fails. If this value is reached without a connection being re-established, the upstream broker is considered permanently offline. The downstream broker no longer routes messages to the upstream broker. The default value is -1, which means that there is no limit.

   retry-interval

   Period, in milliseconds, between subsequent reconnection attempts, if connection to the remote broker has failed. The default value is 500.

   retry-interval-multiplier

   Multiplying factor that is applied to the value of the retry-interval parameter. The default value is 1.

   share-connection

   If there is both a downstream and upstream connection configured for the same broker, then the same connection will be shared, as long as both of the downstream and upstream configurations set the value of this parameter to true. The default value is false.

7. On the local broker, add connectors to the remote brokers. These are the connectors referenced in the static-connectors elements of your federated address configuration. For example:

   <connectors>
      <connector name="eu-west-1-connector">tcp://localhost:61616</connector>
      <connector name="eu-east-1-connector">tcp://localhost:61617</connector>
   </connectors>

Procedure

1. On the local broker, open the <broker-instance-dir>/etc/broker.xml configuration file.

2. Add a <federations> element that includes a <federation> element. For example:

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
       </federation>
   </federations>

3. Add an address policy configuration. For example:

   <federations>
       ...
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <address-policy name="news-address-federation" max-hops="1" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" transformer-ref="news-transformer">
   
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-policy>
   
       </federation>
     ...
   </federations>

4. If you want to transform messages before transmission, add a transformer configuration. For example:

   <federations>
       ...
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <address-policy name="news-address-federation" max-hops="1" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" transformer-ref="news-transformer">
   
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-policy>
   
           <transformer name="news-transformer">
               <class-name>org.foo.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
     ...
   </federations>

5. Add a downstream element for each remote broker. For example:

   <federations>
       ...
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <downstream name="eu-east-1">
                   <static-connectors>
                       <connector-ref>eu-east-connector1</connector-ref>
                   </static-connectors>
                   <transport-connector-ref>netty-connector</transport-connector-ref>
                   <policy ref="news-address-federation"/>
           </downstream>
   
           <downstream name="eu-west-1" >
                   <static-connectors>
                       <connector-ref>eu-west-connector1</connector-ref>
                   </static-connectors>
                   <transport-connector-ref>netty-connector</transport-connector-ref>
                   <policy ref="news-address-federation"/>
           </downstream>
   
           <address-policy name="news-address-federation" max-hops="1" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" transformer-ref="news-transformer">
               <include address-match="queue.bbc.new" />
               <include address-match="queue.usatoday" />
               <include address-match="queue.news.#" />
   
               <exclude address-match="queue.news.sport.#" />
           </address-policy>
   
           <transformer name="news-transformer">
               <class-name>org.foo.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
     ...
   </federations>

   As shown in the preceding configuration, the remote brokers are now considered to be downstream of the local broker. The downstream brokers use the connection information in the configuration to connect back to the local (that is, upstream) broker.

6. On the local broker, add connectors and acceptors used by the local and remote brokers to establish the federation connection. For example:

   <connectors>
      <connector name="netty-connector">tcp://localhost:61616</connector>
      <connector name="eu-west-1-connector">tcp://localhost:61616</connector>
      <connector name="eu-east-1-connector">tcp://localhost:61617</connector>
   </connectors>
   
   <acceptors>
      <acceptor name="netty-acceptor">tcp://localhost:61616</acceptor>
   </acceptors>

   connector name="netty-connector"

   Connector configuration that the local broker sends to the remote broker. The remote broker use this configuration to connect back to the local broker.

   connector name="eu-west-1-connector", connector name="eu-east-1-connector"

   Connectors to remote brokers. The local broker uses these connectors to connect to the remote brokers and share the configuration that the remote brokers need to connect back to the local broker.

   acceptor name="netty-acceptor"

   Acceptor on the local broker that corresponds to the connector used by the remote broker to connect back to the local broker.

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. Within a new <federations> element, add a <federation> element. For example:

   <federations>
     <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
     </federation>
   </federations>

   name

   Name of the federation configuration. In this example, the name corresponds to the name of the downstream broker.

   user

   Shared user name for connection to the upstream brokers.

   password

   Shared password for connection to the upstream brokers.

   Note
   • If user and password credentials differ for upstream brokers, you can separately specify credentials for those brokers when you add them to the configuration. This is described later in this procedure.

3. Within the federation element, add a <queue-policy> element. Specify values for properties of the <queue-policy> element. For example:

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer">
           </queue-policy>
   
       </federation>
   </federations>

   name

   Name of the queue policy. All queue policies that are configured on the broker must have unique names.

   include-federated

   When the value of this property is set to false, the configuration does not re-federate an already-federated consumer (that is, a consumer on a federated queue). This avoids a situation where in a symmetric or closed-loop topology, there are no non-federated consumers, and messages flow endlessly around the system.

   You might set the value of this property to true if you do not have a closed-loop topology. For example, suppose that you have a chain of three brokers, BrokerA, BrokerB, and BrokerC, with a producer at BrokerA and a consumer at BrokerC. In this case, you would want BrokerB to re-federate the consumer to BrokerA.

   priority-adjustment

   When a consumer connects to a queue, its priority is used when the upstream (that is federated) consumer is created. The priority of the federated consumer is adjusted by the value of the priority-adjustment property. The default value of this property is -1, which ensures that the local consumer get prioritized over the federated consumer during load balancing. However, you can change the value of the priority adjustment as needed.

   transformer-ref

   Name of a transformer configuration. You might add a transformer configuration if you want to transform messages during federated message transmission. Transformer configuration is described later in this procedure.

4. Within the <queue-policy> element, add address-matching patterns to include and exclude addresses from the queue policy. For example:

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer">
   
               <include queue-match="#" address-match="queue.bbc.new" />
               <include queue-match="#" address-match="queue.usatoday" />
               <include queue-match="#" address-match="queue.news.#" />
   
               <exclude queue-match="#.local" address-match="#" />
   
           </queue-policy>
   
       </federation>
   </federations>

   include

   The value of the address-match property of this element specifies addresses to include in the queue policy. You can specify an exact address, for example, queue.bbc.new or queue.usatoday. Or, you can use a wildcard expression to specify a matching set of addresses. In the preceding example, the queue policy also includes all address names that start with the string queue.news.

   In combination with the address-match property, you can use the queue-match property to include specific queues on those addresses in the queue policy. Like the address-match property, you can specify an exact queue name, or you can use a wildcard expression to specify a set of queues. In the preceding example, the number sign (#) wildcard character means that all queues on each address or set of addresses are included in the queue policy.

   exclude

   The value of the address-match property of this element specifies addresses to exclude from the queue policy. You can specify an exact address or use a wildcard expression to specify a matching set of addresses. In the preceding example, the number sign (#) wildcard character means that any queues that match the queue-match property across all addresses are excluded. In this case, any queue that ends with the string .local is excluded. This indicates that certain queues are kept as local queues, and not federated.

5. Within the federation element, add a transformer element to reference a custom transformer implementation. For example:

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer">
   
               <include queue-match="#" address-match="queue.bbc.new" />
               <include queue-match="#" address-match="queue.usatoday" />
               <include queue-match="#" address-match="queue.news.#" />
   
               <exclude queue-match="#.local" address-match="#" />
   
           </queue-policy>
   
           <transformer name="news-transformer">
               <class-name>org.foo.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
   </federations>

   name

   Name of the transformer configuration. This name must be unique on the broker in question. You specify this name as a value for the transformer-ref property of the address policy.

   class-name

   Name of a user-defined class that implements the org.apache.activemq.artemis.core.server.transformer.Transformer interface.

   The transformer’s transform() method is invoked with the message before the message is transmitted. This enables you to transform the message header or body before it is federated.

   property

   Used to hold key-value pairs for specific transformer configuration.

6. Within the federation element, add one or more upstream elements. Each upstream element defines an upstream broker connection and the policies to apply to that connection. For example:

   <federations>
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <upstream name="eu-east-1">
               <static-connectors>
                   <connector-ref>eu-east-connector1</connector-ref>
               </static-connectors>
               <policy ref="news-queue-federation"/>
           </upstream>
   
           <upstream name="eu-west-1" >
               <static-connectors>
                   <connector-ref>eu-west-connector1</connector-ref>
               </static-connectors>
               <policy ref="news-queue-federation"/>
           </upstream>
   
           <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer">
   
               <include queue-match="#" address-match="queue.bbc.new" />
               <include queue-match="#" address-match="queue.usatoday" />
               <include queue-match="#" address-match="queue.news.#" />
   
               <exclude queue-match="#.local" address-match="#" />
   
           </queue-policy>
   
           <transformer name="news-transformer">
               <class-name>org.foo.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
   </federations>

   static-connectors

   Contains a list of connector-ref elements that reference connector elements that are defined elsewhere in the broker.xml configuration file of the local broker. A connector defines what transport (TCP, SSL, HTTP, and so on) and server connection parameters (host, port, and so on) to use for outgoing connections. The following step of this procedure shows how to add the connectors referenced by the static-connectors elements of your federated queue configuration.

   policy-ref

   Name of the queue policy configured on the downstream broker that is applied to the upstream broker.

   The additional options that you can specify for an upstream element are described below:

   name

   Name of the upstream broker configuration. In this example, the names correspond to upstream brokers called eu-east-1 and eu-west-1.

   user

   User name to use when creating the connection to the upstream broker. If not specified, the shared user name that is specified in the configuration of the federation element is used.

   password

   Password to use when creating the connection to the upstream broker. If not specified, the shared password that is specified in the configuration of the federation element is used.

   call-failover-timeout

   Similar to call-timeout, but used when a call is made during a failover attempt. The default value is -1, which means that the timeout is disabled.

   call-timeout

   Time, in milliseconds, that a federation connection waits for a reply from a remote broker when it transmits a packet that is a blocking call. If this time elapses, the connection throws an exception. The default value is 30000.

   check-period

   Period, in milliseconds, between consecutive “keep-alive” messages that the local broker sends to a remote broker to check the health of the federation connection. If the federation connection is healthy, the remote broker responds to each keep-alive message. If the connection is unhealthy, when the downstream broker fails to receive a response from the upstream broker, a mechanism called a circuit breaker is used to block federated consumers. See the description of the circuit-breaker-timeout parameter for more information. The default value of the check-period parameter is 30000.

   circuit-breaker-timeout

   A single connection between a downstream and upstream broker might be shared by many federated queue and address consumers. In the event that the connection between the brokers is lost, each federated consumer might try to reconnect at the same time. To avoid this, a mechanism called a circuit breaker blocks the consumers. When the specified timeout value elapses, the circuit breaker re-tries the connection. If successful, consumers are unblocked. Otherwise, the circuit breaker is applied again.

   connection-ttl

   Time, in milliseconds, that a federation connection stays alive if it stops receiving messages from the remote broker. The default value is 60000.

   discovery-group-ref

   As an alternative to defining static connectors for connections to upstream brokers, this element can be used to specify a discovery group that is already configured elsewhere in the broker.xml configuration file. Specifically, you specify an existing discovery group as a value for the discovery-group-name property of this element. For more information about discovery groups, see Section 16.1.5, “Broker discovery methods”.

   ha

   Specifies whether high availability is enabled for the connection to the upstream broker. If the value of this parameter is set to true, the local broker can connect to any available broker in an upstream cluster and automatically fails over to a backup broker if the live upstream broker shuts down. The default value is false.

   initial-connect-attempts

   Number of initial attempts that the downstream broker will make to connect to the upstream broker. If this value is reached without a connection being established, the upstream broker is considered permanently offline. The downstream broker no longer routes messages to the upstream broker. The default value is -1, which means that there is no limit.

   max-retry-interval

   Maximum time, in milliseconds, between subsequent reconnection attempts when connection to the remote broker fails. The default value is 2000.

   reconnect-attempts

   Number of times that the downstream broker will try to reconnect to the upstream broker if the connection fails. If this value is reached without a connection being re-established, the upstream broker is considered permanently offline. The downstream broker no longer routes messages to the upstream broker. The default value is -1, which means that there is no limit.

   retry-interval

   Period, in milliseconds, between subsequent reconnection attempts, if connection to the remote broker has failed. The default value is 500.

   retry-interval-multiplier

   Multiplying factor that is applied to the value of the retry-interval parameter. The default value is 1.

   share-connection

   If there is both a downstream and upstream connection configured for the same broker, then the same connection will be shared, as long as both of the downstream and upstream configurations set the value of this parameter to true. The default value is false.

7. On the local broker, add connectors to the remote brokers. These are the connectors referenced in the static-connectors elements of your federated address configuration. For example:

   <connectors>
      <connector name="eu-west-1-connector">tcp://localhost:61616</connector>
      <connector name="eu-east-1-connector">tcp://localhost:61617</connector>
   </connectors>

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. Add a <federations> element that includes a <federation> element. For example:

   <federations>
     <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
     </federation>
   </federations>

3. Add a queue policy configuration. For example:

   <federations>
       ...
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <queue-policy name="news-queue-federation" priority-adjustment="-5" include-federated="true" transformer-ref="new-transformer">
   
               <include queue-match="#" address-match="queue.bbc.new" />
               <include queue-match="#" address-match="queue.usatoday" />
               <include queue-match="#" address-match="queue.news.#" />
   
               <exclude queue-match="#.local" address-match="#" />
   
           </queue-policy>
   
       </federation>
     ...
   </federations>

4. If you want to transform messages before transmission, add a transformer configuration. For example:

   <federations>
       ...
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <queue-policy name="news-queue-federation" priority-adjustment="-5" include-federated="true" transformer-ref="news-transformer">
   
               <include queue-match="#" address-match="queue.bbc.new" />
               <include queue-match="#" address-match="queue.usatoday" />
               <include queue-match="#" address-match="queue.news.#" />
   
               <exclude queue-match="#.local" address-match="#" />
   
           </queue-policy>
   
           <transformer name="news-transformer">
               <class-name>org.foo.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
     ...
   </federations>

5. Add a downstream element for each remote broker. For example:

   <federations>
       ...
       <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9">
   
           <downstream name="eu-east-1">
               <static-connectors>
                   <connector-ref>eu-east-connector1</connector-ref>
               </static-connectors>
               <transport-connector-ref>netty-connector</transport-connector-ref>
               <policy ref="news-address-federation"/>
           </downstream>
   
           <downstream name="eu-west-1" >
               <static-connectors>
                   <connector-ref>eu-west-connector1</connector-ref>
               </static-connectors>
               <transport-connector-ref>netty-connector</transport-connector-ref>
               <policy ref="news-address-federation"/>
           </downstream>
   
           <queue-policy name="news-queue-federation" priority-adjustment="-5" include-federated="true" transformer-ref="new-transformer">
   
               <include queue-match="#" address-match="queue.bbc.new" />
               <include queue-match="#" address-match="queue.usatoday" />
               <include queue-match="#" address-match="queue.news.#" />
   
               <exclude queue-match="#.local" address-match="#" />
   
           </queue-policy>
   
           <transformer name="news-transformer">
               <class-name>org.foo.NewsTransformer</class-name>
               <property key="key1" value="value1"/>
               <property key="key2" value="value2"/>
           </transformer>
   
       </federation>
     ...
   </federations>

   As shown in the preceding configuration, the remote brokers are now considered to be downstream of the local broker. The downstream brokers use the connection information in the configuration to connect back to the local (that is, upstream) broker.

6. On the local broker, add connectors and acceptors used by the local and remote brokers to establish the federation connection. For example:

   <connectors>
      <connector name="netty-connector">tcp://localhost:61616</connector>
      <connector name="eu-west-1-connector">tcp://localhost:61616</connector>
      <connector name="eu-east-1-connector">tcp://localhost:61617</connector>
   </connectors>
   
   <acceptors>
      <acceptor name="netty-acceptor">tcp://localhost:61616</acceptor>
   </acceptors>

   connector name="netty-connector"

   Connector configuration that the local broker sends to the remote broker. The remote broker use this configuration to connect back to the local broker.

   connector name="eu-west-1-connector" , connector name="eu-east-1-connector"

   Connectors to remote brokers. The local broker uses these connectors to connect to the remote brokers and share the configuration that the remote brokers need to connect back to the local broker.

   acceptor name="netty-acceptor"

   Acceptor on the local broker that corresponds to the connector used by the remote broker to connect back to the local broker.

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. For a given acceptor, add the sslEnabled key and set the value to true. In addition, add the keyStorePath and keyStorePassword keys. Set values that correspond to your broker key store. For example:

   <acceptor name="artemis">tcp://0.0.0.0:61616?sslEnabled=true;keyStorePath=../etc/broker.keystore;keyStorePassword=1234!</acceptor>

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. For the acceptor that you previously configured for one-way TLS, add the needClientAuth key. Set the value to true. For example:

   <acceptor name="artemis">tcp://0.0.0.0:61616?sslEnabled=true;keyStorePath=../etc/broker.keystore;keyStorePassword=1234!;needClientAuth=true</acceptor>

3. The configuration in the preceding step assumes that the client’s certificate is signed by a trusted provider. If the client’s certificate is not signed by a trusted provider (it is self-signed, for example) then the broker needs to import the client’s certificate into a trust store. In this case, add the trustStorePath and trustStorePassword keys. Set values that correspond to your broker trust store. For example:

   <acceptor name="artemis">tcp://0.0.0.0:61616?sslEnabled=true;keyStorePath=../etc/broker.keystore;keyStorePassword=1234!;needClientAuth=true;trustStorePath=../etc/client.truststore;trustStorePassword=5678!</acceptor>

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. Within the security-settings element, add a security-setting element to configure permissions. For example:

   <security-settings>
       <security-setting match="#">
           <permission type="createDurableQueue" roles="user"/>
           <permission type="deleteDurableQueue" roles="user"/>
           <permission type="createNonDurableQueue" roles="user"/>
           <permission type="deleteNonDurableQueue" roles="user"/>
           <permission type="send" roles="user"/>
           <permission type="consume" roles="user"/>
       </security-setting>
   </security-settings>

   The preceding configuration assigns specific permissions for all queues to members of the user role.

3. Open the <broker-instance-dir>/etc/login.config file.

4. Configure the LDAP login module, based on the directory service you are using.

   1. If you are using the Microsoft Active Directory directory service, add a configuration that resembles this example:

      activemq {
        org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule required
           debug=true
           initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
           connectionURL="LDAP://localhost:389"
           connectionUsername="CN=Administrator,CN=Users,OU=System,DC=example,DC=com"
           connectionPassword=redhat.123
           connectionProtocol=s
           connectionTimeout=5000
           authentication=simple
           userBase="dc=example,dc=com"
           userSearchMatching="(CN={0})"
           userSearchSubtree=true
           readTimeout=5000
           roleBase="dc=example,dc=com"
           roleName=cn
           roleSearchMatching="(member={0})"
           roleSearchSubtree=true
           ;
      };

      Note

      If you are using Microsoft Active Directory, and a value that you need to specify for an attribute of connectionUsername contains a space (for example, OU=System Accounts), then you must enclose the value in a pair of double quotes ("") and use a backslash (\) to escape each double quote in the pair. For example, connectionUsername="CN=Administrator,CN=Users,OU=\"System Accounts\",DC=example,DC=com".

   2. If you are using the ApacheDS directory service, add a configuration that resembles this example:

      activemq {
        org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule required
           debug=true
           initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
           connectionURL="ldap://localhost:10389"
           connectionUsername="uid=admin,ou=system"
           connectionPassword=secret
           connectionProtocol=s
           connectionTimeout=5000
           authentication=simple
           userBase="dc=example,dc=com"
           userSearchMatching="(uid={0})"
           userSearchSubtree=true
           userRoleName=
           readTimeout=5000
           roleBase="dc=example,dc=com"
           roleName=cn
           roleSearchMatching="(member={0})"
           roleSearchSubtree=true
           ;
      };

      debug

      Turn debugging on (true) or off (false). The default value is false.

      initialContextFactory

      Must always be set to com.sun.jndi.ldap.LdapCtxFactory

      connectionURL

      Location of the directory server using an LDAP URL, __<ldap://Host:Port>. One can optionally qualify this URL, by adding a forward slash, /, followed by the DN of a particular node in the directory tree. The default port of Apache DS is 10389 while for Microsoft AD the default is 389.

      connectionUsername

      Distinguished Name (DN) of the user that opens the connection to the directory server. For example, uid=admin,ou=system. Directory servers generally require clients to present username/password credentials in order to open a connection.

      connectionPassword

      Password that matches the DN from connectionUsername. In the directory server, in the Directory Information Tree (DIT), the password is normally stored as a userPassword attribute in the corresponding directory entry.

      connectionProtocol

      Any value is supported but is effectively unused. This option must be set explicitly because it has no default value.

      connectionTimeout

      Specify the maximum time, in milliseconds, that the broker can take to connect to the directory server. If the broker cannot connect to the directory sever within this time, it aborts the connection attempt. If you specify a value of zero or less for this property, the timeout value of the underlying TCP protocol is used instead. If you do not specify a value, the broker waits indefinitely to establish a connection, or the underlying network times out.

      When connection pooling has been requested for a connection, then this property specifies the maximum time that the broker waits for a connection when the maximum pool size has already been reached and all connections in the pool are in use. If you specify a value of zero or less, the broker waits indefinitely for a connection to become available. Otherwise, the broker aborts the connection attempt when the maximum wait time has been reached.

      authentication

      Specifies the authentication method used when binding to the LDAP server. This parameter can be set to either simple (which requires a username and password) or none (which allows anonymous access).

      userBase

      Select a particular subtree of the DIT to search for user entries. The subtree is specified by a DN, which specifies the base node of the subtree. For example, by setting this option to ou=User,ou=ActiveMQ,ou=system, the search for user entries is restricted to the subtree beneath the ou=User,ou=ActiveMQ,ou=system node.

      userSearchMatching

      Specify an LDAP search filter, which is applied to the subtree selected by userBase. See the Section 5.4.1.1, “Search matching parameters” section below for more information.

      userSearchSubtree

      Specify the search depth for user entries, relative to the node specified by userBase. This option is a Boolean. Specifying a value of false means that the search tries to match one of the child entries of the userBase node (maps to javax.naming.directory.SearchControls.ONELEVEL_SCOPE). Specifying a value of true means that the search tries to match any entry belonging to the subtree of the userBase node (maps to javax.naming.directory.SearchControls.SUBTREE_SCOPE).

      userRoleName

      Name of the attribute of the user entry that contains a list of role names for the user. Role names are interpreted as group names by the broker’s authorization plug-in. If this option is omitted, no role names are extracted from the user entry.

      readTimeout

      Specify the maximum time, in milliseconds, that the broker can wait to receive a response from the directory server to an LDAP request. If the broker does not receive a response from the directory server in this time, the broker aborts the request. If you specify a value of zero or less, or you do not specify a value, the broker waits indefinitely for a response from the directory server to an LDAP request.

      roleBase

      If role data is stored directly in the directory server, one can use a combination of role options (roleBase, roleSearchMatching, roleSearchSubtree, and roleName) as an alternative to (or in addition to) specifying the userRoleName option. This option selects a particular subtree of the DIT to search for role/group entries. The subtree is specified by a DN, which specifies the base node of the subtree. For example, by setting this option to ou=Group,ou=ActiveMQ,ou=system, the search for role/group entries is restricted to the subtree beneath the ou=Group,ou=ActiveMQ,ou=system node.

      roleName

      Attribute type of the role entry that contains the name of the role/group (such as C, O, OU, etc.). If this option is omitted the role search feature is effectively disabled.

      roleSearchMatching

      Specify an LDAP search filter, which is applied to the subtree selected by roleBase. See the Section 5.4.1.1, “Search matching parameters” section below for more information.

      roleSearchSubtree

      Specify the search depth for role entries, relative to the node specified by roleBase. If set to false (which is the default) the search tries to match one of the child entries of the roleBase node (maps to javax.naming.directory.SearchControls.ONELEVEL_SCOPE). If true it tries to match any entry belonging to the subtree of the roleBase node (maps to javax.naming.directory.SearchControls.SUBTREE_SCOPE).

      Note

      Apache DS uses the OID portion of DN path. Microsoft Active Directory uses the CN portion. For example, you might use a DN path such as oid=testuser,dc=example,dc=com in Apache DS, while you might use a DN path such as cn=testuser,dc=example,dc=com in Microsoft Active Directory.

5. Start or restart the broker (service or process).

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. Within the security-settings element, add the security-setting-plugin element. For example:

   <security-settings>
       <security-setting-plugin class-name="org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin">
           <setting name="initialContextFactory" value="com.sun.jndi.ldap.LdapCtxFactory"/>
           <setting name="connectionURL" value="ldap://localhost:1024"/>`ou=destinations,o=ActiveMQ,ou=system`
           <setting name="connectionUsername" value="uid=admin,ou=system"/>
           <setting name="connectionPassword" value="secret"/>
           <setting name="connectionProtocol" value="s"/>
           <setting name="authentication" value="simple"/>
       </security-setting-plugin>
   </security-settings>

   class-name

   The implementation is org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin.

   initialContextFactory

   The initial context factory used to connect to LDAP. It must always be set to com.sun.jndi.ldap.LdapCtxFactory (that is, the default value).

   connectionURL

   Specifies the location of the directory server using an LDAP URL, <ldap://Host:Port>. You can optionally qualify this URL by adding a forward slash, /, followed by the distinguished name (DN) of a particular node in the directory tree. For example, ldap://ldapserver:10389/ou=system. The default value is ldap://localhost:1024.

   connectionUsername

   The DN of the user that opens the connection to the directory server. For example, uid=admin,ou=system. Directory servers generally require clients to present username/password credentials in order to open a connection.

   connectionPassword

   The password that matches the DN from connectionUsername. In the directory server, in the Directory Information Tree (DIT), the password is normally stored as a userPassword attribute in the corresponding directory entry.

   connectionProtocol

   Currently unused. In the future, this option might allow you to select the Secure Socket Layer (SSL) for the connection to the directory server. This option must be set explicitly because it has no default value.

   authentication

   Specifies the authentication method used when binding to the LDAP server. Valid values for this parameter are simple (username and password) or none (anonymous). The default value is simple.

   Note

   Simple Authentication and Security Layer (SASL) authentication is not supported.

1. From a command prompt, use the mask utility to encrypt the password:

   $ <broker_instance_dir>/bin/artemis mask <password>

   result: 3a34fd21b82bf2a822fa49a8d8fa115d

2. Open the <broker_instance_dir>/etc/login.config file. Locate the connectionPassword parameter:

   connectionPassword = <password>

3. Replace the plain-text password with the encrypted value:

   connectionPassword = 3a34fd21b82bf2a822fa49a8d8fa115d

4. Wrap the encrypted value with the identifier "ENC()":

   connectionPassword = "ENC(3a34fd21b82bf2a822fa49a8d8fa115d)"

Procedure

1. Stop the broker.

   1. On Linux:

      <broker_instance_dir>/bin/artemis stop

   2. On Windows:

      <broker_instance_dir>\bin\artemis-service.exe stop

2. Open the <broker_instance_dir>/etc/broker.xml configuration file.

3. Add the name-value pair saslMechanisms=GSSAPI to the query string of the URL for the acceptor.

   <acceptor name="amqp">
     tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI
   </acceptor>

   The preceding configuration means that the acceptor uses the GSSAPI mechanism when authenticating Kerberos credentials.

4. (Optional) The PLAIN and ANONYMOUS SASL mechanisms are also supported. To specify multiple mechanisms, use a comma-separated list. For example:

   <acceptor name="amqp">
     tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI,PLAIN
   </acceptor>

   The result is an acceptor that uses both the GSSAPI and PLAIN SASL mechanisms.

5. Start the broker.

   1. On Linux:

      <broker_instance_dir>/bin/artemis run

   2. On Windows:

      <broker_instance_dir>\bin\artemis-service.exe start

Procedure

1. Stop the broker.

   1. On Linux:

      <broker_instance_dir>/bin/artemis stop

   2. On Windows:

      <broker_instance_dir>\bin\artemis-service.exe stop

2. Open the <broker_instance_dir>/etc/login.config configuration file.

3. Add a configuration scope named amqp-sasl-gssapi. The following example shows configuration for the Krb5LoginModule found in Oracle and OpenJDK versions of the JDK.

   amqp-sasl-gssapi {
       com.sun.security.auth.module.Krb5LoginModule required
       isInitiator=false
       storeKey=true
       useKeyTab=true
       principal="amqp/my_broker_host@example.com"
       debug=true;
   };

   amqp-sasl-gssapi

   By default, the GSSAPI mechanism implementation on the broker uses a JAAS configuration scope named amqp-sasl-gssapi to obtain its Kerberos acceptor credentials.

   Krb5LoginModule

   This version of the Krb5LoginModule is provided by the Oracle and OpenJDK versions of the JDK. Verify the fully qualified class name of the Krb5LoginModule and its available options by referring to the documentation from your Java vendor.

   useKeyTab

   The Krb5LoginModule is configured to use a Kerberos keytab when authenticating a principal. Keytabs are generated using tooling from your Kerberos environment. See the documentation from your vendor for details about generating Kerberos keytabs.

   principal

   The Principal is set to amqp/my_broker_host@example.com. This value must correspond to the service principal created in your Kerberos environment. See the documentation from your vendor for details about creating service principals.

4. Start the broker.

   1. On Linux:

      <broker_instance_dir>/bin/artemis run

   2. On Windows:

      <broker_instance_dir>\bin\artemis-service.exe start

Procedure

1. Stop the broker.

   1. On Linux:

      <broker_instance_dir>/bin/artemis stop

   2. On Windows:

      <broker_instance_dir>\bin\artemis-service.exe stop

2. Open the <broker_instance_dir>/etc/login.config configuration file.

3. Add configuration for the AMQ Broker Krb5LoginModule and the LDAPLoginModule. Verify the configuration options by referring to the documentation from your LDAP provider.

   An example configuration is shown below.

   org.apache.activemq.artemis.spi.core.security.jaas.Krb5LoginModule required
       ;
   org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule optional
       initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
       connectionURL="ldap://localhost:1024"
       authentication=GSSAPI
       saslLoginConfigScope=broker-sasl-gssapi
       connectionProtocol=s
       userBase="ou=users,dc=example,dc=com"
       userSearchMatching="(krb5PrincipalName={0})"
       userSearchSubtree=true
       authenticateUser=false
       roleBase="ou=system"
       roleName=cn
       roleSearchMatching="(member={0})"
       roleSearchSubtree=false
       ;

   Note

   The version of the Krb5LoginModule shown in the preceding example is distributed with AMQ Broker and transforms the Kerberos identity into a broker identity that can be used by other AMQ modules for role mapping.

4. Start the broker.

   1. On Linux:

      <broker_instance_dir>/bin/artemis run

   2. On Windows:

      <broker_instance_dir>\bin\artemis-service.exe start

Procedure

1. Open the <broker-instance-dir>/etc/boostrap.xml configuration file.

2. In the security-manager element, for the class-name attribute, specify the class that is a user-defined implementation of the org.apache.activemq.artemis.spi.core.security.ActiveMQSecurityManager5 interface. For example:

   <broker xmlns="http://activemq.org/schema">
      ...
      <security-manager class-name="com.foo.MySecurityManager">
         <property key="myKey1" value="myValue1"/>
         <property key="myKey2" value="myValue2"/>
      </security-manager>
      ...
   </broker>

Procedure

1. Navigate to the directory to the directory that contains the custom security manager example.

   $ cd <install-dir>/examples/features/standard/security-manager

2. Run the example.

   $ mvn verify

Procedure

1. From a command prompt, use the mask utility to encrypt a password:

   $ <broker_instance_dir>/bin/artemis mask <password>

   result: 3a34fd21b82bf2a822fa49a8d8fa115d

2. Open the <broker_instance_dir>/etc/broker.xml configuration file containing the plain-text password that you want to mask:

   <cluster-password>
     <password>
   </cluster-password>

3. Replace the plain-text password with the encrypted value:

   <cluster-password>
     3a34fd21b82bf2a822fa49a8d8fa115d
   </cluster-password>

4. Wrap the encrypted value with the identifier ENC():

   <cluster-password>
     ENC(3a34fd21b82bf2a822fa49a8d8fa115d)
   </cluster-password>

Procedure

1. As the owner of the BROKER_INSTANCE_DIR, stop the broker. In the example below, the user amq-broker was created during the installation of AMQ Broker.

   su - amq-broker
   cd __BROKER_INSTANCE_DIR__/bin
   $ ./artemis stop

2. (Optional) Run the following CLI command to get a full list of parameters for the data tool. Note that by default, the tool uses settings found in BROKER_INSTANCE_DIR/etc/broker.xml.

   $ ./artemis help data compact.

3. Run the following CLI command to compact the data.

   $ ./artemis data compact.

4. After the tool has successfully compacted the data, restart the broker.

   $ ./artemis run

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. Within the <core> element, add the following connectors:

   • A connector that defines how other brokers can connect to this one
   • One or more connectors that define how this broker can connect to other brokers in the cluster

   <configuration>
       <core>
           ...
           <connectors>
               <connector name="netty-connector">tcp://localhost:61617</connector>  1
               <connector name="broker2">tcp://localhost:61618</connector>  2
               <connector name="broker3">tcp://localhost:61619</connector>
           </connectors>
           ...
       </core>
   </configuration>

   1

   This connector defines connection information that other brokers can use to connect to this one. This information will be sent to other brokers in the cluster during discovery.

   2

   The broker2 and broker3 connectors define how this broker can connect to two other brokers in the cluster, one of which will always be available. If there are other brokers in the cluster, they will be discovered by one of these connectors when the initial connection is made.

   For more information about connectors, see Section 2.2, “About Connectors”.

3. Add a cluster connection and configure it to use static discovery.

   By default, the cluster connection will load balance messages for all addresses in a symmetric topology.

   <configuration>
       <core>
           ...
           <cluster-connections>
               <cluster-connection name="my-cluster">
                   <connector-ref>netty-connector</connector-ref>
                   <static-connectors>
                       <connector-ref>broker2-connector</connector-ref>
                       <connector-ref>broker3-connector</connector-ref>
                   </static-connectors>
               </cluster-connection>
           </cluster-connections>
           ...
       </core>
   </configuration>

   cluster-connection

   Use the name attribute to specify the name of the cluster connection.

   connector-ref

   The connector that defines how other brokers can connect to this one.

   static-connectors

   One or more connectors that this broker can use to make an initial connection to another broker in the cluster. After making this initial connection, the broker will discover the other brokers in the cluster. You only need to configure this property if the cluster uses static discovery.

4. Configure any additional properties for the cluster connection.

   These additional cluster connection properties have default values that are suitable for most common use cases. Therefore, you only need to configure these properties if you do not want the default behavior. For more information, see Appendix C, Cluster Connection Configuration Elements.

5. Create the cluster user and password.

   AMQ Broker ships with default cluster credentials, but you should change them to prevent unauthorized remote clients from using these default credentials to connect to the broker.

   Important

   The cluster password must be the same on every broker in the cluster.

   <configuration>
       <core>
           ...
           <cluster-user>cluster_user</cluster-user>
           <cluster-password>cluster_user_password</cluster-password>
           ...
       </core>
   </configuration>

6. Repeat this procedure on each additional broker.

   You can copy the cluster configuration to each additional broker. However, do not copy any of the other AMQ Broker data files (such as the bindings, journal, and large messages directories). These files must be unique among the nodes in the cluster or the cluster will not form properly.

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. Within the <core> element, add a connector.

   This connector defines connection information that other brokers can use to connect to this one. This information will be sent to other brokers in the cluster during discovery.

   <configuration>
       <core>
           ...
           <connectors>
               <connector name="netty-connector">tcp://localhost:61617</connector>
           </connectors>
           ...
       </core>
   </configuration>

3. Add a UDP broadcast group.

   The broadcast group enables the broker to push information about its cluster connection to the other brokers in the cluster. This broadcast group uses UDP to broadcast the connection settings:

   <configuration>
       <core>
           ...
           <broadcast-groups>
               <broadcast-group name="my-broadcast-group">
                   <local-bind-address>172.16.9.3</local-bind-address>
                   <local-bind-port>-1</local-bind-port>
                   <group-address>231.7.7.7</group-address>
                   <group-port>9876</group-port>
                   <broadcast-period>2000</broadcast-period>
                   <connector-ref>netty-connector</connector-ref>
               </broadcast-group>
           </broadcast-groups>
           ...
       </core>
   </configuration>

   The following parameters are required unless otherwise noted:

   broadcast-group

   Use the name attribute to specify a unique name for the broadcast group.

   local-bind-address

   The address to which the UDP socket is bound. If you have multiple network interfaces on your broker, you should specify which one you want to use for broadcasts. If this property is not specified, the socket will be bound to an IP address chosen by the operating system. This is a UDP-specific attribute.

   local-bind-port

   The port to which the datagram socket is bound. In most cases, use the default value of -1, which specifies an anonymous port. This parameter is used in connection with local-bind-address. This is a UDP-specific attribute.

   group-address

   The multicast address to which the data will be broadcast. It is a class D IP address in the range 224.0.0.0 - 239.255.255.255 inclusive. The address 224.0.0.0 is reserved and is not available for use. This is a UDP-specific attribute.

   group-port

   The UDP port number used for broadcasting. This is a UDP-specific attribute.

   broadcast-period (optional)

   The interval in milliseconds between consecutive broadcasts. The default value is 2000 milliseconds.

   connector-ref

   The previously configured cluster connector that should be broadcasted.

4. Add a UDP discovery group.

   The discovery group defines how this broker receives connector information from other brokers. The broker maintains a list of connectors (one entry for each broker). As it receives broadcasts from a broker, it updates its entry. If it does not receive a broadcast from a broker for a length of time, it removes the entry.

   This discovery group uses UDP to discover the brokers in the cluster:

   <configuration>
       <core>
           ...
           <discovery-groups>
               <discovery-group name="my-discovery-group">
                   <local-bind-address>172.16.9.7</local-bind-address>
                   <group-address>231.7.7.7</group-address>
                   <group-port>9876</group-port>
                   <refresh-timeout>10000</refresh-timeout>
               </discovery-group>
           <discovery-groups>
           ...
       </core>
   </configuration>

   The following parameters are required unless otherwise noted:

   discovery-group

   Use the name attribute to specify a unique name for the discovery group.

   local-bind-address (optional)

   If the machine on which the broker is running uses multiple network interfaces, you can specify the network interface to which the discovery group should listen. This is a UDP-specific attribute.

   group-address

   The multicast address of the group on which to listen. It should match the group-address in the broadcast group that you want to listen from. This is a UDP-specific attribute.

   group-port

   The UDP port number of the multicast group. It should match the group-port in the broadcast group that you want to listen from. This is a UDP-specific attribute.

   refresh-timeout (optional)

   The amount of time in milliseconds that the discovery group waits after receiving the last broadcast from a particular broker before removing that broker’s connector pair entry from its list. The default is 10000 milliseconds (10 seconds).

   Set this to a much higher value than the broadcast-period on the broadcast group. Otherwise, brokers might periodically disappear from the list even though they are still broadcasting (due to slight differences in timing).

5. Create a cluster connection and configure it to use dynamic discovery.

   By default, the cluster connection will load balance messages for all addresses in a symmetric topology.

   <configuration>
       <core>
           ...
           <cluster-connections>
               <cluster-connection name="my-cluster">
                   <connector-ref>netty-connector</connector-ref>
                   <discovery-group-ref discovery-group-name="my-discovery-group"/>
               </cluster-connection>
           </cluster-connections>
           ...
       </core>
   </configuration>

   cluster-connection

   Use the name attribute to specify the name of the cluster connection.

   connector-ref

   The connector that defines how other brokers can connect to this one.

   discovery-group-ref

   The discovery group that this broker should use to locate other members of the cluster. You only need to configure this property if the cluster uses dynamic discovery.

6. Configure any additional properties for the cluster connection.

   These additional cluster connection properties have default values that are suitable for most common use cases. Therefore, you only need to configure these properties if you do not want the default behavior. For more information, see Appendix C, Cluster Connection Configuration Elements.

7. Create the cluster user and password.

   AMQ Broker ships with default cluster credentials, but you should change them to prevent unauthorized remote clients from using these default credentials to connect to the broker.

   Important

   The cluster password must be the same on every broker in the cluster.

   <configuration>
       <core>
           ...
           <cluster-user>cluster_user</cluster-user>
           <cluster-password>cluster_user_password</cluster-password>
           ...
       </core>
   </configuration>

8. Repeat this procedure on each additional broker.

   You can copy the cluster configuration to each additional broker. However, do not copy any of the other AMQ Broker data files (such as the bindings, journal, and large messages directories). These files must be unique among the nodes in the cluster or the cluster will not form properly.

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. Within the <core> element, add a connector.

   This connector defines connection information that other brokers can use to connect to this one. This information will be sent to other brokers in the cluster during discovery.

   <configuration>
       <core>
           ...
           <connectors>
               <connector name="netty-connector">tcp://localhost:61617</connector>
           </connectors>
           ...
       </core>
   </configuration>

3. Within the <core> element, add a JGroups broadcast group.

   The broadcast group enables the broker to push information about its cluster connection to the other brokers in the cluster. This broadcast group uses JGroups to broadcast the connection settings:

   <configuration>
       <core>
           ...
           <broadcast-groups>
               <broadcast-group name="my-broadcast-group">
                   <jgroups-file>test-jgroups-file_ping.xml</jgroups-file>
                   <jgroups-channel>activemq_broadcast_channel</jgroups-channel>
                   <broadcast-period>2000</broadcast-period>
                   <connector-ref>netty-connector</connector-ref>
               </broadcast-group>
           </broadcast-groups>
           ...
       </core>
   </configuration>

   The following parameters are required unless otherwise noted:

   broadcast-group

   Use the name attribute to specify a unique name for the broadcast group.

   jgroups-file

   The name of JGroups configuration file to initialize JGroups channels. The file must be in the Java resource path so that the broker can load it.

   jgroups-channel

   The name of the JGroups channel to connect to for broadcasting.

   broadcast-period (optional)

   The interval, in milliseconds, between consecutive broadcasts. The default value is 2000 milliseconds.

   connector-ref

   The previously configured cluster connector that should be broadcasted.

4. Add a JGroups discovery group.

   The discovery group defines how connector information is received. The broker maintains a list of connectors (one entry for each broker). As it receives broadcasts from a broker, it updates its entry. If it does not receive a broadcast from a broker for a length of time, it removes the entry.

   This discovery group uses JGroups to discover the brokers in the cluster:

   <configuration>
       <core>
           ...
           <discovery-groups>
               <discovery-group name="my-discovery-group">
                   <jgroups-file>test-jgroups-file_ping.xml</jgroups-file>
                   <jgroups-channel>activemq_broadcast_channel</jgroups-channel>
                   <refresh-timeout>10000</refresh-timeout>
               </discovery-group>
           <discovery-groups>
           ...
       </core>
   </configuration>

   The following parameters are required unless otherwise noted:

   discovery-group

   Use the name attribute to specify a unique name for the discovery group.

   jgroups-file

   The name of JGroups configuration file to initialize JGroups channels. The file must be in the Java resource path so that the broker can load it.

   jgroups-channel

   The name of the JGroups channel to connect to for receiving broadcasts.

   refresh-timeout (optional)

   The amount of time in milliseconds that the discovery group waits after receiving the last broadcast from a particular broker before removing that broker’s connector pair entry from its list. The default is 10000 milliseconds (10 seconds).

   Set this to a much higher value than the broadcast-period on the broadcast group. Otherwise, brokers might periodically disappear from the list even though they are still broadcasting (due to slight differences in timing).

5. Create a cluster connection and configure it to use dynamic discovery.

   By default, the cluster connection will load balance messages for all addresses in a symmetric topology.

   <configuration>
       <core>
           ...
           <cluster-connections>
               <cluster-connection name="my-cluster">
                   <connector-ref>netty-connector</connector-ref>
                   <discovery-group-ref discovery-group-name="my-discovery-group"/>
               </cluster-connection>
           </cluster-connections>
           ...
       </core>
   </configuration>

   cluster-connection

   Use the name attribute to specify the name of the cluster connection.

   connector-ref

   The connector that defines how other brokers can connect to this one.

   discovery-group-ref

   The discovery group that this broker should use to locate other members of the cluster. You only need to configure this property if the cluster uses dynamic discovery.

6. Configure any additional properties for the cluster connection.

   These additional cluster connection properties have default values that are suitable for most common use cases. Therefore, you only need to configure these properties if you do not want the default behavior. For more information, see Appendix C, Cluster Connection Configuration Elements.

7. Create the cluster user and password.

   AMQ Broker ships with default cluster credentials, but you should change them to prevent unauthorized remote clients from using these default credentials to connect to the broker.

   Important

   The cluster password must be the same on every broker in the cluster.

   <configuration>
       <core>
           ...
           <cluster-user>cluster_user</cluster-user>
           <cluster-password>cluster_user_password</cluster-password>
           ...
       </core>
   </configuration>

8. Repeat this procedure on each additional broker.

   You can copy the cluster configuration to each additional broker. However, do not copy any of the other AMQ Broker data files (such as the bindings, journal, and large messages directories). These files must be unique among the nodes in the cluster or the cluster will not form properly.