Migrating to Red Hat AMQ 7

If you plan to migrate a production environment, you should seek further assistance and guidance from a Red Hat support representative. You can open a support case at https://access.redhat.com/support/.

You can use this guide to understand the configuration changes that might be required to create a AMQ Broker 7 configuration to which existing OpenWire JMS clients can connect.

This guide does not describe how to migrate the following features:

Before learning about the specific configuration changes in each AMQ feature area, you should first understand the important conceptual differences between AMQ 6 and AMQ 7.

There are several key architectural differences in AMQ 7. In addition, a new message addressing and routing model has been implemented in this release.

Before migrating to AMQ 7, you should understand the key new features, enhancements, and known issues. For a list, see the Release Notes for Red Hat AMQ Broker 7.8.

This document uses the following conventions for the sudo command and file paths.

The sudo command

In this document, sudo is used for any command that requires root privileges. You should always exercise caution when using sudo, as any changes can affect the entire system.

For more information about using sudo, see The sudo Command.

About the use of file paths in this document

In this document, all file paths are valid for Linux, UNIX, and similar operating systems (for example, /home/...). If you are using Microsoft Windows, you should use the equivalent Microsoft Windows paths (for example, C:\Users\...).

Before migrating to AMQ 7, your environment should meet the following requirements:

Before migrating to AMQ 7, you should create a AMQ broker instance. You can configure this broker instance as you learn about the configuration differences in AMQ 7 that are described in this guide.

When you installed AMQ Broker, the binaries, libraries, and other important files needed to run AMQ Broker were installed. However, in AMQ 7, you must explicitly create a broker instance whenever a new broker is needed. Each broker instance is a separate directory containing its own configuration and runtime data.

Each AMQ 7 broker instance contains its own directory. You should understand the directory content and where to find the configuration files for the broker instance you created.

When you create a broker instance, the following directory structure is created:

$ ls /var/lib/amq7/mybroker
bin  data  etc  lock  log  tmp

You should understand how the broker instance you created should be configured and which configuration files you will need to edit.

Like AMQ 6, you configure AMQ 7 broker instances by editing plain text and XML files. Changing a broker’s configuration involves opening the appropriate configuration file in the broker instance’s directory, locating the proper element in the XML hierarchy, and then making the actual change—​which typically involves adding or removing XML elements and attributes.

Within BROKER_INSTANCE_DIR/etc, there are several configuration files that you can edit:

Migrating to AMQ 7 primarily involves editing the broker.xml file. For more information about the broker.xml structure and default configuration settings, see Understanding the default broker configuration in Configuring AMQ Broker.

To verify that your existing clients can connect to the broker instance you created, you should start the broker instance and send some test messages.

AMQ 6 and AMQ Broker 7 both enable you to define the way that clients connect to the broker. These connection points were called transport connectors in AMQ 6, but now are called acceptors in AMQ Broker 7.

AMQ 6 provided multiple implementations of the transport layer (such as TCP and NIO), which meant that you had to use different transport connectors depending on whether you wanted a client connection point to use a blocking or non-blocking transport. In AMQ Broker 7, the transport layer uses Netty only, which is non-blocking by default. There are two types of acceptors in AMQ Broker 7:

AMQ 6 also required you to use separate transport connectors for each messaging protocol. In AMQ Broker 7, the low-level transport (either TCP or In-VM) is distinct from the messaging protocol used by the client (such as AMQP, MQTT, and so on). This means that a single acceptor can use multiple protocols on the same port. In fact, an acceptor will accept all supported message protocols unless you explicitly restrict the protocols that it can use.

For example, the default acceptor in AMQ Broker 7 automatically accepts all message protocols:

<acceptor name="artemis">tcp://0.0.0.0:61616?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=CORE,AMQP,STOMP,HORNETQ,MQTT,OPENWIRE;useEpoll=true;amqpCredits=1000;amqpLowCredits=300</acceptor>

You use the BROKER_INSTANCE_DIR/etc/broker.xml configuration file to configure acceptors to accept incoming client connections for your broker instance.

The broker.xml configuration file contains the following default acceptors in the <acceptors> section:

<configuration>
...
  <core>
  ...
     <acceptors>
       <!-- Acceptor for every supported protocol -->
       <acceptor name="artemis">tcp://0.0.0.0:61616?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=CORE,AMQP,STOMP,HORNETQ,MQTT,OPENWIRE;useEpoll=true;amqpCredits=1000;amqpLowCredits=300</acceptor> 1

       <!-- AMQP Acceptor.  Listens on default AMQP port for AMQP traffic.-->
       <acceptor name="amqp">tcp://0.0.0.0:5672?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=AMQP;useEpoll=true;amqpCredits=1000;amqpMinCredits=300</acceptor>

       <!-- STOMP Acceptor. -->
       <acceptor name="stomp">tcp://0.0.0.0:61613?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=STOMP;useEpoll=true</acceptor>

       <!-- HornetQ Compatibility Acceptor.  Enables HornetQ Core and STOMP for legacy HornetQ clients. -->
       <acceptor name="hornetq">tcp://0.0.0.0:5445?protocols=HORNETQ,STOMP;useEpoll=true</acceptor>

       <!-- MQTT Acceptor -->
       <acceptor name="mqtt">tcp://0.0.0.0:1883?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=MQTT;useEpoll=true</acceptor>
       ...
  </core>
</configuration>

To configure the incoming client connections for your broker instance, you can modify the configuration properties for any of the default acceptors, or you can add new acceptors. This example shows a new acceptor configured to accept TCP connections using the OpenWire protocol:

<acceptor name="my-acceptor">tcp://0.0.0.0:61613?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=OPENWIRE;useEpoll=true</acceptor>

In both AMQ Broker 7 and AMQ 6, authentication is provided by pluggable login modules based on the Java Authentication and Authorization Service (JAAS). However, groups in AMQ 6 are now called roles in AMQ Broker 7.

In addition, the names and locations of the login modules have changed in AMQ Broker 7.

The syntax for adding users and roles is also different.

You can access the AMQ 7 broker instance using the default username and password that you created when you created the broker instance. To enable additional users to access the broker instance, you can configure user authentication for the broker using any of the following methods:

AMQ 6 implemented JMS concepts such as queues, topics, and durable subscriptions as directly-configurable destinations.

<destinations>
     <queue physicalName="my-queue" />
     <topic physicalName="my-topic" />
</destinations>

AMQ Broker 7 uses addresses, routing types, and queues to achieve queue and topic-like behavior. An address represents a messaging endpoint. Queues are associated with addresses. A routing type defines how messages are distributed to the queues associated with an address. There are two routing types: Anycast distributes messages to a single queue within the matching address, and Multicast distributes messages to every queue associated with the address.

By associating queues with addresses and routing types, you can implement a variety of messaging patterns, such as point-to-point (queues) and publish-subscribe (topic-like).

<address name="address.foo">
  <anycast>
    <queue name="my-queue"/>
  </anycast>
</address>

<address name="topic.foo">
  <multicast>
    <queue name="my-topic-1"/>
    <queue name="my-topic-2"/>
  </multicast>
</address>

You use the BROKER_INSTANCE_DIR/etc/broker.xml configuration file to configure addresses and queues for your broker instance.

The broker.xml configuration file contains the following default addressing configuration in the <addresses> section. There are default entries for the Dead Letter Queue (DLQ) and Expiry Queue (ExpiryQueue):

<addresses>
   <address name="DLQ">
      <anycast>
         <queue name="DLQ" />
      </anycast>
   </address>
      <address name="ExpiryQueue">
         <anycast>
            <queue name="ExpiryQueue" />
         </anycast>
   </address>
</addresses>

You can configure addressing for your broker instance by using any of the following methods:

Like AMQ 6, AMQ Broker 7 enables you to secure incoming network connections using SSL/TLS. However, there are some differences in configuration syntax and configuration properties.

In AMQ 6, transport layer security was configured by creating an SSL context to define the keystores and truststores, and then adding SSL attributes to each transport connector that you wanted to secure.

In AMQ Broker 7, the transport layer is based on Netty, which uses SSL natively. This means that to configure transport layer security, you just add the necessary SSL attributes to each acceptor that you want to secure. You do not need to add a separate SSL context.

For example, the following configuration accepts secure connections from an OpenWire client:

You can configure either one-way or two-way TLS. The following table describes these methods:

AMQ Broker 7 provides a role-based security model in which you apply security settings to queues based on their addresses. This security model is similar to AMQ 6; however, the permissions and wildcard syntax are different, and authorization is configured differently.

<configuration ...>
  <core ...>
    ...
    <security-settings>
      <security-setting match="#"> 1
        <permission type="createNonDurableQueue" roles="admin"/> 2
        <permission type="deleteNonDurableQueue" roles="admin"/>
        <permission type="createDurableQueue" roles="admin"/>
        <permission type="deleteDurableQueue" roles="admin"/>
        <permission type="createAddress" roles="admin"/>
        <permission type="deleteAddress" roles="admin"/>
        <permission type="consume" roles="admin"/>
        <permission type="browse" roles="admin"/>
        <permission type="send" roles="admin"/>
        <permission type="manage" roles="admin"/>
      </security-setting>
    </security-settings>
    ...
  </core>
</configuration>

In AMQ 6, resource limits and policies were configured as destination policies in the broker’s configuration file.

In AMQ Broker 7, you define resource limits and policies for an address or set of addresses. When the broker instance receives a message, the resource limits and policies defined for the message’s address are applied to the message.

To configure resource limits and policies in AMQ Broker 7, you use the BROKER_INSTANCE_DIR/etc/broker.xml configuration file to define <address-setting> elements with the appropriate configuration properties.

The broker.xml configuration file contains the following default address settings configuration:

<address-settings>
    <!-- if you define auto-create on certain queues, management has to be auto-create -->
    <address-setting match="activemq.management#"> 1
        <dead-letter-address>DLQ</dead-letter-address>
        <expiry-address>ExpiryQueue</expiry-address>
        <redelivery-delay>0</redelivery-delay>
        <!-- with -1 only the global-max-size is in use for limiting -->
        <max-size-bytes>-1</max-size-bytes>
        <message-counter-history-day-limit>10</message-counter-history-day-limit>
        <address-full-policy>PAGE</address-full-policy>
        <auto-create-queues>true</auto-create-queues>
        <auto-create-addresses>true</auto-create-addresses>
        <auto-create-jms-queues>true</auto-create-jms-queues>
        <auto-create-jms-topics>true</auto-create-jms-topics>
    </address-setting>
    <!--default for catch all-->
    <address-setting match="#"> 2
        <dead-letter-address>DLQ</dead-letter-address>
        <expiry-address>ExpiryQueue</expiry-address>
        <redelivery-delay>0</redelivery-delay>
        <!-- with -1 only the global-max-size is in use for limiting -->
        <max-size-bytes>-1</max-size-bytes>
        <message-counter-history-day-limit>10</message-counter-history-day-limit>
        <address-full-policy>PAGE</address-full-policy>
        <auto-create-queues>true</auto-create-queues>
        <auto-create-addresses>true</auto-create-addresses>
        <auto-create-jms-queues>true</auto-create-jms-queues>
        <auto-create-jms-topics>true</auto-create-jms-topics>
    </address-setting>
</address-settings>

To configure resource limits and policies, you specify an address or set of addresses (using <address-setting>), and then add resource limit and policy properties to it. These properties are applied to each message sent to the address (or addresses) that you specified.

Like AMQ 6, in AMQ Broker 7, you can add resource limits and policies to control how the broker handles certain aspects of how and when messages are delivered, the number of delivery attempts that should be made, and when messages should expire. However, the configuration properties you use to define these resource limits and policies are different in AMQ Broker 7.

This section compares the <policyEntry> configuration properties in AMQ 6 to the equivalent <address-setting> properties in AMQ Broker 7. For complete details on each configuration property in AMQ Broker 7, see Address Setting Configuration Elements in Configuring AMQ Broker.

...
<address-settings>
    <address-setting match="#">
        <dead-letter-address>DLQ</dead-letter-address>
        <expiry-address>ExpiryQueue</expiry-address>
        ...
    </address-setting>
    ...
</address-settings>
...

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

AMQ Broker 7 uses a different type of message journal than AMQ 6, and it does not use a journal index.

AMQ 6 used KahaDB for a message store, and it maintained a message journal index to track the position of each message inside the journal. This index enabled the broker to pull paged messages from its journal in batches and place them in its cache.

By default, AMQ Broker 7 uses an in-memory message journal from which the broker can dispatch messages. Therefore, AMQ Broker 7 does not use a message journal index. If a broker instance runs out of memory, messages are paged as they arrive at the broker, but before they are queued. These message page files are stored on disk sequentially in the same order in which they arrived. Then, when memory is freed on the broker, the messages are moved from the page file to the journal on the broker. Because the journal is read sequentially, there is no need to keep an index of messages in the journal.

In addition, AMQ Broker 7 also offers a different JDBC-based message journal option that was not available in AMQ 6.

The AMQ Broker 7 message journal supports the following shared file systems:

You use the BROKER_INSTANCE_DIR/etc/broker.xml configuration file to configure the broker instance’s message journal.

The broker.xml configuration file contains the following default message journal configuration properties:

<core>

    <name>0.0.0.0</name>

    <persistence-enabled>true</persistence-enabled>

    <journal-type>ASYNCIO</journal-type>

    <paging-directory>./data/paging</paging-directory>

    <bindings-directory>./data/bindings</bindings-directory>

    <journal-directory>./data/journal</journal-directory>

    <large-messages-directory>./data/large-messages</large-messages-directory>

    <journal-datasync>true</journal-datasync>

    <journal-min-files>2</journal-min-files>

    <journal-pool-files>-1</journal-pool-files>

    <journal-buffer-timeout>744000</journal-buffer-timeout>

    <disk-scan-period>5000</disk-scan-period>

    <max-disk-usage>90</max-disk-usage>

    <global-max-size>104857600</global-max-size>

    ...

</core>

To configure the message journal, you can change the default values for any of the journal configuration properties. You can also add additional configuration properties.

AMQ 6 and AMQ Broker 7 both offer a number of configuration properties to control how the broker persists messages. This section compares the configuration properties in the AMQ 6 KahaDB journal to the equivalent properties in the AMQ Broker 7 in-memory message journal.

For complete details on each message persistence configuration property for the in-memory message journal, see the following:

In AMQ Broker 7, broker networks are called broker clusters. The brokers in the cluster are connected by cluster connections (which reference connector elements). Members of a cluster can be configured to discover each other dynamically (using UDP or JGroups), or statically (by manually specifying a list of cluster members).

A cluster configuration is a required prerequisite for high-availability (HA). You must configure the cluster before you can configure HA, even if the cluster consists of only a single live broker.

You can configure broker clusters in many different topologies, though symmetric and chain clusters are the most common. Regardless of the topology, you can scale clusters up and down without message loss (as long as you have configured the broker to send its messages to another broker in the cluster).

Broker clusters distribute (and redistribute) messages differently than broker networks in AMQ 6. In AMQ 6, messages always arrived on a specific queue and were then pulled from one broker to another based on consumer interest. In AMQ Broker 7, queue definitions and consumers are shared across the cluster, and messages are routed across the cluster as they are received at the broker.

You configure a broker cluster by creating a broker instance for each member of the cluster, and then adding the cluster settings to each broker instance.

Cluster settings consist of the following:

<!-- Clustering configuration -->
<broadcast-groups>
    <broadcast-group name="my-broadcast-group">
        <group-address>${udp-address:231.7.7.7}</group-address>
        <group-port>9876</group-port>
        <broadcast-period>100</broadcast-period>
        <connector-ref>netty-connector</connector-ref>
    </broadcast-group>
</broadcast-groups>

<discovery-groups>
    <discovery-group name="my-discovery-group">
        <group-address>${udp-address:231.7.7.7}</group-address>
        <group-port>9876</group-port>
        <refresh-timeout>10000</refresh-timeout>
    </discovery-group>
</discovery-groups>

<cluster-connections>
    <cluster-connection name="my-cluster">
        <connector-ref>netty-connector</connector-ref>
        <retry-interval>500</retry-interval>
        <use-duplicate-detection>true</use-duplicate-detection>
        <message-load-balancing>ON_DEMAND</message-load-balancing>
        <max-hops>1</max-hops>
        <discovery-group-ref discovery-group-name="my-discovery-group"/>
    </cluster-connection>
</cluster-connections>

<connectors>
   <connector name="netty-connector">tcp://localhost:61616</connector>
   <!-- connector to broker2 -->
   <connector name="broker2-connector">tcp://localhost:61716</connector>
</connectors>


<cluster-connections>
   <cluster-connection name="my-cluster">
      <address>jms</address>
      <connector-ref>netty-connector</connector-ref>
      <retry-interval>500</retry-interval>
      <use-duplicate-detection>true</use-duplicate-detection>
      <message-load-balancing>STRICT</message-load-balancing>
      <max-hops>2</max-hops>
      <static-connectors allow-direct-connections-only="true">
         <connector-ref>broker2-connector</connector-ref>
      </static-connectors>
   </cluster-connection>
</cluster-connections>

<connectors>
   <connector name="netty-connector">tcp://localhost:61716</connector>
   <!-- connector to broker3 -->
   <connector name="broker3-connector">tcp://localhost:61816</connector>
</connectors>


<cluster-connections>
   <cluster-connection name="my-cluster">
      <address>jms</address>
      <connector-ref>netty-connector</connector-ref>
      <retry-interval>500</retry-interval>
      <use-duplicate-detection>true</use-duplicate-detection>
      <message-load-balancing>STRICT</message-load-balancing>
      <max-hops>1</max-hops>
      <static-connectors allow-direct-connections-only="true">
         <connector-ref>broker3-connector</connector-ref>
      </static-connectors>
   </cluster-connection>
</cluster-connections>

<connectors>
   <connector name="netty-connector">tcp://localhost:61816</connector>
</connectors>

<cluster-connections>
   <cluster-connection name="my-cluster">
      <address>jms</address>
      <connector-ref>netty-connector</connector-ref>
      <retry-interval>500</retry-interval>
      <use-duplicate-detection>true</use-duplicate-detection>
      <message-load-balancing>STRICT</message-load-balancing>
      <max-hops>0</max-hops>
   </cluster-connection>
</cluster-connections>

The following table compares the broker network configuration properties in AMQ 6 to the equivalent cluster-connection properties in AMQ Broker 7:

High availability in AMQ Broker 7 differs from AMQ 6 based on how the master is determined and when the broker connections become active.

In AMQ Broker 7, the master and slave roles are fixed. You specify which broker instance is the master, and the slave only becomes active in certain conditions. In AMQ 6, the master and slave roles were not fixed. Instead, the brokers in an HA pair would compete for a lock, and the winner would become the master.

In AMQ Broker 7, in an HA pair, the slave broker’s acceptors are active even if the broker is inactive. In AMQ 6, the slave broker’s transport connectors did not become active until the broker became active.

You configure HA by adding an HA policy configuration to the BROKER_INSTANCE_DIR/etc/broker.xml configuration file of each broker.

<configuration>
  <core>
    ...
    <ha-policy>
       <shared-store>
         <master/>
            <failover-on-shutdown>true</failover-on-shutdown>
       </shared-store>
    </ha-policy>
    ...
  </core>
</configuration>

The slave broker is configured like this. By setting failover-on-shutdown to true, this slave broker will become the master if the current master broker is shut down:

<configuration>
  <core>
    ...
    <ha-policy>
       <shared-store>
          <slave/>
            <failover-on-shutdown>true</failover-on-shutdown>
       </shared-store>
    </ha-policy>
    ...
  </core>
</configuration>

Revised on 2020-12-03 08:49:05 UTC