Chapter 2. Preparing for the Migration

download PDF

Before learning about the configuration changes in each feature area, you should ensure that your environment meets the migration requirements and understand how broker instances are configured in AMQ Broker 7.

2.1. Migration Requirements

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

AMQ 6 requirements
  • You should be running AMQ 6.2.x or later.
  • OpenWire clients should use OpenWire version 10 or later.
AMQ 7 requirements

2.2. Creating a Broker Instance

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.


Keeping broker installation and configuration separate means that you can install AMQ Broker just once in a central location and then create as many broker instances as you require. Additionally, keeping installation and configuration separate makes it easier to manage and upgrade your brokers as needed.


  • AMQ Broker 7 must be installed.


  1. Navigate to the location where you want to create the broker instance.

    $ sudo mkdir /var/lib/amq7
    $ cd /var/lib/amq7
  2. Do one of the following to create the broker instance:


    AMQ Broker 7 is installed on the same machine as AMQ 6

    Use the artemis create command with the --port-offset parameter to create the new broker instance that will not conflict with your existing AMQ 6 broker.


    AMQ Broker 7 and AMQ 6 both listen for client traffic on the same set of default ports. Therefore, you must offset the default ports on the AMQ Broker broker instance to avoid potential conflicts.

    This example creates a new broker instance that listens for client traffic on different ports than the AMQ 6 broker:

    $ sudo INSTALL_DIR/bin/artemis create mybroker --port-offset 100 --user admin --password pass --role amq --allow-anonymous true

    AMQ Broker 7 and AMQ 6 are installed on separate machines

    Use the artemis create command to create the new broker instance.

    This example creates a new broker instance and prompts you for any required values:

    $ sudo INSTALL_DIR/bin/artemis create mybroker
    Creating ActiveMQ Artemis instance at: /var/lib/amq7/mybroker
    --user: is mandatory with this configuration:
    Please provide the default username:
    --password: is mandatory with this configuration:
    Please provide the default password:
    --role: is mandatory with this configuration:
    Please provide the default role:

Related Information

For full details on creating broker instances, see Creating a broker instance in Getting Started with AMQ Broker.

2.3. Understanding the Broker Instance Directory Structure

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
The location where the broker instance was created. This is a different location than the AMQ Broker installation.
Shell scripts for starting and stopping the broker instance.
Contains broker state data, such as the message store.
The broker instance’s configuration files. These are the files you need to access to configure the broker instance.
Contains the cli.lock file.
Log files for the broker instance.
A utility directory for temporary files.

2.4. How Brokers are Configured in AMQ 7

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:

Configuration FileDescription


The main configuration file. Similar to activemq.xml in AMQ 6, you use this file to configure most aspects of the broker, such as acceptors for incoming network connections, security settings, message addresses, and so on.


The file that AMQ Broker uses to start the broker instance. You use it to change the location of the main broker configuration file, configure the web server, and set some security settings.

You use this file to set logging properties for the broker instance. This file is similar to the org.ops4j.pax.logging.cfg file in AMQ 6.

JAAS configuration files (login.config,,

You use these files to set up authentication for user access to the broker instance.

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.

2.5. Verifying that Clients Can Connect to the Broker Instance

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.


  1. Start the broker instance by using one of the following commands:

    To…​Use this command…​

    Start the broker in the foreground

    $ sudo BROKER_INSTANCE_DIR/bin/artemis run

    Start the broker as a service

    $ sudo BROKER_INSTANCE_DIR/bin/artemis-service start

    The broker instance starts. By default, an OpenWire connector is started on the broker instance on the same port as your AMQ 6 broker. This should enable your existing clients to connect to the broker instance.

  2. If you want to check the status of the broker instance, open the BROKER_INSTANCE_DIR/logs/artemis.log file.
  3. In your AMQ 6 broker, use the producer command to send some test messages to the AMQ 7 broker instance.

    This command sends five test messages to a AMQ 7 broker instance hosted on localhost and listening on the default acceptor:

    JBossA-MQ:karaf@root> producer --brokerUrl tcp:// --message "Test message" --messageCount 5

    If you offset the port numbers when you created the broker instance (using --port-offset), make sure that you use the correct port number for the broker URL. For example, if you set the port offset to 100, then you would need to set --brokerUrl to tcp://

  4. In your AMQ 6 broker, use the consumer command to verify that you can consume the test messages that you sent to the AMQ 7 broker instance.

    This command receives the five test messages sent to the AMQ 7 broker instance:

    JBossA-MQ:karaf@root> consumer --brokerUrl tcp://

    You can also verify that the messages were sent and received by checking the INSTALL_DIR/data/log/amq.log file on the AMQ 6 broker.

  5. Stop the broker instance:

    $ BROKER_INSTANCE_DIR/bin/artemis stop
Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.