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 You should have a supported operating system and JVM. You can view supported configurations for AMQ 7 at: https://access.redhat.com/articles/2791941 AMQ Broker 7 should be installed. For more information, see Installing AMQ Broker in Getting Started with AMQ Broker . 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. Note 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. Prerequisites AMQ Broker 7 must be installed. Procedure Navigate to the location where you want to create the broker instance. Do one of the following to create the broker instance: If... Then... 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. 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: 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: 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 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: BROKER_INSTANCE_DIR The location where the broker instance was created. This is a different location than the AMQ Broker installation. /bin Shell scripts for starting and stopping the broker instance. /data Contains broker state data, such as the message store. /etc The broker instance's configuration files. These are the files you need to access to configure the broker instance. /lock Contains the cli.lock file. /log Log files for the broker instance. /tmp 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 File Description broker.xml 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. bootstrap.xml 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. logging.properties 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 , users.properties , roles.properties ) 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. Procedure Start the broker instance by using one of the following commands: To... Use this command... Start the broker in the foreground Start the broker as a service 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 BROKER_INSTANCE_DIR /logs/artemis.log file. 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://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 --brokerUrl to tcp://0.0.0.0:61716 . 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://0.0.0.0:61616 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. Stop the broker instance:

Commands:
sudo mkdir /var/lib/amq7 cd /var/lib/amq7
sudo INSTALL_DIR /bin/artemis create mybroker --port-offset 100 --user admin --password pass --role amq --allow-anonymous true
sudo INSTALL_DIR /bin/artemis create mybroker
ls /var/lib/amq7/mybroker bin data etc lock log tmp
sudo BROKER_INSTANCE_DIR /bin/artemis run
sudo BROKER_INSTANCE_DIR /bin/artemis-service start
JBossA-MQ:karaf@root> producer --brokerUrl tcp://0.0.0.0:61616 --message "Test message" --messageCount 5
JBossA-MQ:karaf@root> consumer --brokerUrl tcp://0.0.0.0:61616
BROKER_INSTANCE_DIR /bin/artemis stop