Chapter 2. Preparing for the Migration
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.
Navigate to the location where you want to create the broker instance.
$ sudo mkdir /var/lib/amq7 $ cd /var/lib/amq7
Do one of the following to create the broker instance:
AMQ Broker 7 is installed on the same machine as AMQ 6
artemis createcommand with the
--port-offsetparameter to create the new broker instance that will not conflict with your existing AMQ 6 broker.Note
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
artemis createcommand 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: user --password: is mandatory with this configuration: Please provide the default password: password --role: is mandatory with this configuration: Please provide the default role: amq --allow-anonymous
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.
- 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.
BROKER_INSTANCE_DIR/etc, there are several configuration files that you can edit:
| || |
The main configuration file. Similar to
| || |
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
JAAS configuration files (
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.
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.
If you want to check the status of the broker instance, open the
In your AMQ 6 broker, use the
producercommand 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://0.0.0.0:61616 --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
In your AMQ 6 broker, use the
consumercommand 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://0.0.0.0:61616
You can also verify that the messages were sent and received by checking the
INSTALL_DIR/data/log/amq.logfile on the AMQ 6 broker.
Stop the broker instance:
$ BROKER_INSTANCE_DIR/bin/artemis stop