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 <broker_instance_dir>/etc/broker.xml configuration file.
2. Set the stompEnableMessageId parameter to true for the acceptor used for STOMP connections, as shown in the following example:

Procedure

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

Procedure

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.
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.22.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 14.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 14.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 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>

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

   By default, the broker is configured to use journal-based persistence, as shown below.

   <configuration>
     <core>
       ...
       <persistence-enabled>true</persistence-enabled>
       <journal-type>ASYNCIO</journal-type>
       <bindings-directory>./data/bindings</bindings-directory>
       <journal-directory>./data/journal</journal-directory>
       <journal-datasync>true</journal-datasync>
       <journal-min-files>2</journal-min-files>
       <journal-pool-files>-1</journal-pool-files>
       <journal-device-block-size>4096</journal-device-block-size>
       <journal-file-size>10M</journal-file-size>
       <journal-buffer-timeout>12000</journal-buffer-timeout>
       <journal-max-io>4096</journal-max-io>
       ...
     </core>
   </configuration>

   persistence-enabled

   If the value of this parameter is set to true, the broker uses the file-based journal for message persistence.

   journal-type

   Type of journal to use. If set to ASYNCIO, the broker first attempts to use AIO. If AIO is not found, the broker uses NIO.

   bindings-directory

   File system location of the bindings journal. The default value is relative to the <broker_instance_dir> directory.

   journal-directory

   File system location of the message journal. The default value is relative to the <broker_instance_dir> directory.

   journal-datasync

   If the value of this parameter is set to true, the broker uses the fdatasync function to confirm disk writes.

   journal-min-files

   Number of journal files to initially create when the broker starts.

   journal-pool-files

   Number of files to keep after reclaiming unused files. The default value of -1 means that no files are deleted during cleanup.

   journal-device-block-size

   Maximum size, in bytes, of the data blocks used by the journal on your storage device. The default value is 4096 bytes.

   journal-file-size

   Maximum size, in bytes, of each journal file in the specified journal directory. When this limit is reached, the broker starts a new file. This parameter also supports byte notation (for example, K, M, G), or the binary equivalents (Ki, Mi, Gi). If this parameter is not explicitly specified in your configuration, the default value is 10485760 bytes (10MiB).

   journal-buffer-timeout

   Specifies how often, in nanoseconds, the broker flushes the journal buffer. AIO typically uses a higher flush rate than NIO, so the broker maintains different default values for both NIO and AIO. If this parameter not explicitly specified in your configuration, the default value for NIO is 3333333 nanoseconds (that is, 300 times per second). The default value for AIO is 50000 nanoseconds (that is, 2000 times per second).

   journal-max-io

   Maximum number of write requests that can be in the IO queue at any one time. If the queue becomes full, the broker blocks further writes until space is available.

   If you are using NIO, this value should always be 1. If you are using AIO andthis parameter not explicitly specified in your configuration, the default value is 500.

2. Based on the preceding descriptions, adjust your persistence configuration as needed for your storage device.

Procedure

1. On Linux, to manage the disk write cache settings, use the tools hdparm (for IDE disks) or sdparm or sginfo (for SDSI/SATA disks).
2. On Windows, to manage the disk writer cache settings, right-click the disk. Select Properties.

Procedure

1. Add the appropriate JDBC client libraries to the broker runtime. To do this, add the relevant .jar files to the <broker_instance_dir>/lib directory.
2. Open the <broker_instance_dir>/etc/broker.xml configuration file.

3. Within the core element, add a store element that contains a database-store element.

   <configuration>
     <core>
       <store>
          <database-store>
          </database-store>
       </store>
     </core>
   </configuration>

4. Within the database-store element, add configuration parameters for JDBC persistence and specify values. For example:

   <configuration>
     <core>
       <store>
          <database-store>
             <jdbc-connection-url>jdbc:oracle:data/oracle/database-store;create=true</jdbc-connection-url>
             <jdbc-user>ENC(5493dd76567ee5ec269d11823973462f)</jdbc-user>
             <jdbc-password>ENC(56a0db3b71043054269d11823973462f)</jdbc-password>
             <bindings-table-name>BINDINGS_TABLE</bindings-table-name>
             <message-table-name>MESSAGE_TABLE</message-table-name>
             <large-message-table-name>LARGE_MESSAGES_TABLE</large-message-table-name>
             <page-store-table-name>PAGE_STORE_TABLE</page-store-table-name>
             <node-manager-store-table-name>NODE_MANAGER_TABLE</node-manager-store-table-name>
             <jdbc-driver-class-name>oracle.jdbc.driver.OracleDriver</jdbc-driver-class-name>
             <jdbc-network-timeout>10000</jdbc-network-timeout>
             <jdbc-lock-renew-period>2000</jdbc-lock-renew-period>
             <jdbc-lock-expiration>20000</jdbc-lock-expiration>
             <jdbc-journal-sync-period>5</jdbc-journal-sync-period>
          </database-store>
       </store>
     </core>
   </configuration>

   jdbc-connection-url

   Full JDBC connection URL for your database server. The connection URL should include all configuration parameters and the database name.

   jdbc-user

   Encrypted user name for your database server. For more information about encrypting user names and passwords for use in configuration files, see Section 5.9, “Encrypting passwords in configuration files”.

   jdbc-password

   Encrypted password for your database server. For more information about encrypting user names and passwords for use in configuration files, see Section 5.9, “Encrypting passwords in configuration files”.

   bindings-table-name

   Name of the table in which bindings data is stored. Specifying a table name enables you to share a single database between multiple servers, without interference.

   message-table-name

   Name of the table in which message data is stored. Specifying this table name enables you to share a single database between multiple servers, without interference.

   large-message-table-name

   Name of the table in which large messages and related data are persisted. In addition, if a client streams a large message in chunks, the chunks are stored in this table. Specifying this table name enables you to share a single database between multiple servers, without interference.

   page-store-table-name

   Name of the table in which paged store directory information is stored. Specifying this table name enables you to share a single database between multiple servers, without interference.

   node-manager-store-table-name

   Name of the table in which the shared store high-availability (HA) locks for live and backup brokers and other HA-related data is stored on the broker server. Specifying this table name enables you to share a single database between multiple servers, without interference. Each live-backup pair that uses shared store HA must use the same table name. You cannot share the same table between multiple (and unrelated) live-backup pairs.

   jdbc-driver-class-name

   Fully-qualified class name of the JDBC database driver. For information about supported databases, see Red Hat AMQ 7 Supported Configurations on the Red Hat Customer Portal.

   jdbc-network-timeout

   JDBC network connection timeout, in milliseconds. The default value is 20000 milliseconds. When using a JDBC for shared store HA, it is recommended to set the timeout to a value less than or equal to jdbc-lock-expiration.

   jdbc-lock-renew-period

   Length, in milliseconds, of the renewal period for the current JDBC lock. When this time elapses, the broker can renew the lock. It is recommended to set a value that is several times smaller than the value of jdbc-lock-expiration. This gives the broker sufficient time to extend the lease and also gives the broker time to try to renew the lock in the event of a connection problem. The default value is 2000 milliseconds.

   jdbc-lock-expiration

   Time, in milliseconds, that the current JDBC lock is considered owned (that is, acquired or renewed), even if the value of jdbc-lock-renew-period has elapsed.

   The broker periodically tries to renew a lock that it owns according to the value of jdbc-lock-renew-period. If the broker fails to renew the lock (for example, due to a connection problem) the broker keeps trying to renew the lock until the value of jdbc-lock-expiration has passed since the lock was last successfully acquired or renewed.

   An exception to the renewal behavior described above is when another broker acquires the lock. This can happen if there is a time misalignment between the Database Management System (DBMS) and the brokers, or if there is a long pause for garbage collection. In this case, the broker that originally owned the lock considers the lock lost and does not try to renew it.

   After the expiration time elapses, if the JDBC lock has not been renewed by the broker that currently owns it, another broker can establish a JDBC lock.

   The default value of jdbc-lock-expiration is 20000 milliseconds.

   jdbc-journal-sync-period

   Duration, in milliseconds, for which the broker journal synchronizes with JDBC. The default value is 5 milliseconds.

Procedure

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

2. Within the database-store element that you previously added for your JDBC configuration, remove the jdbc-driver-class-name, jdbc-connection-url, jdbc-user, jdbc-password, parameters. Later in this procedure, you will replace these with corresponding DBCP configuration parameters.

   Note

   If you do not explicitly remove the preceding parameters, the corresponding DBCP parameters that you add later in this procedure take precedence.

3. Within the database-store element, add a data-source-properties element. For example:

   <store>
       <database-store>
           <data-source-properties>
           </data-source-properties>
           <bindings-table-name>BINDINGS</bindings-table-name>
           <message-table-name>MESSAGES</message-table-name>
           <large-message-table-name>LARGE_MESSAGES</large-message-table-name>
           <page-store-table-name>PAGE_STORE</page-store-table-name>
           <node-manager-store-table-name>NODE_MANAGER_STORE</node-manager-store-table-name>
           <jdbc-network-timeout>10000</jdbc-network-timeout>
           <jdbc-lock-renew-period>2000</jdbc-lock-renew-period>
           <jdbc-lock-expiration>20000</jdbc-lock-expiration>
           <jdbc-journal-sync-period>5</jdbc-journal-sync-period>
       </database-store>
   </store>

4. Within the new data-source-properties element, add DBCP data source properties for connection pooling. Specify key-value pairs. For example:

   <store>
       <database-store>
           <data-source-properties>
               <data-source-property key="driverClassName" value="com.mysql.jdbc.Driver" />
               <data-source-property key="url" value="jdbc:mysql://localhost:3306/artemis" />
               <data-source-property key="username" value="ENC(5493dd76567ee5ec269d1182397346f)"/>
               <data-source-property key="password" value="ENC(56a0db3b71043054269d1182397346f)"/>
               <data-source-property key="poolPreparedStatements" value="true" />
               <data-source-property key="maxTotal" value="-1" />
           </data-source-properties>
           <bindings-table-name>BINDINGS</bindings-table-name>
           <message-table-name>MESSAGES</message-table-name>
           <large-message-table-name>LARGE_MESSAGES</large-message-table-name>
           <page-store-table-name>PAGE_STORE</page-store-table-name>
           <node-manager-store-table-name>NODE_MANAGER_STORE</node-manager-store-table-name>
           <jdbc-network-timeout>10000</jdbc-network-timeout>
           <jdbc-lock-renew-period>2000</jdbc-lock-renew-period>
           <jdbc-lock-expiration>20000</jdbc-lock-expiration>
           <jdbc-journal-sync-period>5</jdbc-journal-sync-period>
       </database-store>
   </store>

   driverClassName

   Fully-qualified class name of the JDBC database driver.

   url

   Full JDBC connection URL for your database server.

   username

   Encrypted user name for your database server. You can also specify this value as unencrypted, plain text. For more information about encrypting user names and passwords for use in configuration files, see Section 5.9, “Encrypting passwords in configuration files”.

   password

   Encrypted password for your database server. You can also specify this value as unencrypted, plain text. For more information about encrypting user names and passwords for use in configuration files, see Section 5.9, “Encrypting passwords in configuration files”.

   poolPreparedStatements

   When the value of this parameter is set to true, the pool can have an unlimited number of cached prepared statements. This reduces initialization costs.

   maxTotal

   Maximum number of connections in the pool. When the value of this parameter is set to -1, there is no limit.

Procedure

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

2. Within the core element, add the paging-directory element. Specify a location for the paging directory in your file system.

   <configuration ...>
     <core ...>
       ...
       <paging-directory>/path/to/paging-directory</paging-directory>
       ...
     </core>
   </configuration>

   For each address that you subsequently configure for paging, the broker adds a dedicated directory within the paging directory that you have specified.

Procedure

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

2. For an address-setting element that you have configured for a matching address or set of addresses, add configuration elements to specify maximum memory usage and define paging behavior. For example:

   <address-settings>
       <address-setting match="my.paged.address">
           ...
           <max-size-bytes>104857600</max-size-bytes>
           <page-size-bytes>10485760</page-size-bytes>
           <address-full-policy>PAGE</address-full-policy>
           ...
       </address-setting>
   </address-settings>

   max-size-bytes

   Maximum size, in bytes, of the memory allowed for the address before the broker executes the policy specified for address-full-policy. The default value is -1, which means that there is no limit. The value that you specify also supports byte notation such as "K", "MB", and "GB".

   page-size-bytes

   Size, in bytes, of each page file used on the paging system. The default value is 10485760 (that is, 10 MiB). The value that you specify also supports byte notation such as "K", "MB", and "GB".

   address-full-policy

   Action that the broker takes when then the maximum size for an address has been reached. The default value is PAGE. Valid values are:

   PAGE

   The broker pages any further messages to disk.

   DROP

   The broker silently drops any further messages.

   FAIL

   The broker drops any further messages and issues exceptions to client message producers.

   BLOCK

   Client message producers block when they try to send further messages.

   Additional paging configuration elements that are not shown in the preceding example are described below.

   page-max-cache-size

   Number of page files that the broker keeps in memory to optimize IO during paging navigation. The default value is 5.

   page-sync-timeout

   Time, in nanoseconds, between periodic page synchronizations. If you are using an asynchronous IO journal (that is, journal-type is set to ASYNCIO in the broker.xml configuration file), the default value is 3333333. If you are using a standard Java NIO journal (that is, journal-type is set to NIO), the default value is the configured value of the journal-buffer-timeout parameter.

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. Within the core element, add the global-max-size element and specify a value. For example:

   <configuration>
     <core>
       ...
       <global-max-size>1GB</global-max-size>
       ...
     </core>
   </configuration>

   global-max-size

   Total amount of memory, in bytes, that the broker can use for all addresses. When this limit is reached, for the address associated with an incoming message, the broker executes the policy that is specified as a value for address-full-policy. The default value of global-max-size is half of the maximum memory available to the Java virtual machine (JVM) that is hosting the broker.

   The value for global-max-size is in bytes, but also supports byte notation (for example, "K", "Mb", "GB").

   In the preceding example, the broker is configured to use a maximum of one gigabyte of available memory when processing messages.

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/broker.xml configuration file.

3. Within the core element add the max-disk-usage configuration element and specify a value. For example:

   <configuration>
     <core>
       ...
       <max-disk-usage>50</max-disk-usage>
       ...
     </core>
   </configuration>

   max-disk-usage

   Maximum percentage of the available disk space that the broker can use when paging messages. When this limit is reached, the broker blocks incoming messages rather than paging them. The default value is 90.

   In the preceding example, the broker is limited to using fifty percent of disk space when paging messages.

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/broker.xml configuration file.

2. For an address-setting element that you have configured for a matching address or set of addresses, add configuration elements to define message blocking behavior. For example:

   <address-settings>
       <address-setting match="my.blocking.address">
           ...
           <max-size-bytes>300000</max-size-bytes>
           <address-full-policy>BLOCK</address-full-policy>
           ...
       </address-setting>
   </address-settings>

   max-size-bytes

   Maximum size, in bytes, of the memory allowed for the address before the broker executes the policy specified for address-full-policy. The value that you specify also supports byte notation such as "K", "MB", and "GB".

   Note

   If you specify max-size-bytes in an address-setting element, the value applies to each matching address. Specifying this value does not mean that the total size of all matching addresses is limited to the value of max-size-bytes.

   address-full-policy

   Action that the broker takes when then the maximum size for an address has been reached.

Procedure

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

2. For an address-setting element that you have configured for a matching address or set of addresses, specify the maximum size of all AMQP messages in memory. For example:

   <address-settings>
       <address-setting match="my.amqp.blocking.address">
           ...
           <max-size-bytes-reject-threshold>300000</max-size-bytes-reject-threshold>
           ...
       </address-setting>
   </address-settings>

   max-size-bytes-reject-threshold

   Maximum size, in bytes, of the memory allowed for the address before the broker blocks further AMQP messages. The value that you specify also supports byte notation such as "K", "MB", and "GB". By default, max-size-bytes-reject-threshold is set to -1, which means that there is no maximum size.

   Note

   If you specify max-size-bytes-reject-threshold in an address-setting element, the value applies to each matching address. Specifying this value does not mean that the total size of all matching addresses is limited to the value of max-size-bytes-reject-threshold.

Procedure