Chapter 3. Patching and Upgrading

3.1. About Patches and Upgrades

Red Hat releases new versions of AMQ Broker to the Customer Support Portal. Update your brokers to the newest version to ensure that they have the latest enhancements and fixes. In general, Red Hat releases a new version of AMQ Broker in one of three ways:

Major Release
A major upgrade or migration is required when an application is moved from one major release to another, for example, from AMQ Broker 6 to AMQ Broker 7. This type of migration is not addressed in this guide. For instructions on how to upgrade from previous releases of AMQ Broker, see Migrating to Red Hat JBoss AMQ 7.
Minor Release
AMQ Broker periodically provides point releases, which are minor updates that include new features, as well as bug and security fixes. If you plan to upgrade from one AMQ Broker point release to another, for example, from AMQ Broker 7.0 to AMQ Broker 7.1, code changes should not be required for applications that do not use private, unsupported, or tech preview components. For instructions on how to upgrade from one minor release to another, see Patching and Upgrading Your Broker later in this chapter.
Cumulative Patch
AMQ Broker also periodically provides cumulative patches that contain minor features and fixes. Cumulative patches increment the minor release version by the last digit, for example from 7.0.1 to 7.0.2. A cumulative patch should not require code changes, however, some patches may require configuration changes. See Patching and Upgrading Your Broker later in this chapter for details.

3.2. Patching and Upgrading Your Broker

The procedure for patching or upgrading AMQ Broker is similar to the one for installation: you download an archive from the Customer Support Portal, and then extract it. Sections in this chapter are divided by operating system and describe the steps used to patch or upgrade your brokers.

Patching and Upgrading on Linux

Note that the name of the actual archive that you download will differ from the one used in the following examples.

Procedure

  1. Download the desired patch from the Red Hat Customer Support Portal by following the instructions provided in Downloading an AMQ Broker Archive.
  2. Change the owner of the patch to the same user that owns the AMQ Broker installation to be patched.

    sudo chown amq-broker:amq-broker jboss-amq-7.x.x.redhat-1.zip
  3. Move the patch to the directory created during the original installation of AMQ Broker. In the next example, the directory /opt/redhat is used.

    sudo mv jboss-amq-7.x.x.redhat-1.zip /opt/redhat
  4. As the directory owner, extract the contents of the compressed archive. The archive is kept in a compressed format. In the following example, the user amq-broker extracts the archive by using the unzip command.

    su - amq-broker
    cd /opt/redhat
    unzip jboss-amq-7.x.x.redhat-1.zip
  5. Stop the broker if it is running.

    BROKER_INSTANCE_DIR/bin/artemis stop
  6. As a precaution, backup the broker’s instance directory by copying it to the current user’s home directory.

    cp -r BROKER_INSTANCE_DIR ~/
  7. (Optional) Note the current version of the broker. After the broker stops, a line similar to the one below is displayed at the end of the broker’s log file, which can be found at BROKER_INSTANCE_DIR/log/artemis.log.

    INFO  [org.apache.activemq.artemis.core.server] AMQ221002: Apache ActiveMQ Artemis Message Broker version 2.0.0.amq-700005-redhat-1 [4782d50d-47a2-11e7-a160-9801a793ea45] stopped, uptime 28 minutes
  8. Edit the BROKER_INSTANCE_DIR/etc/artemis.profile configuration file and set the ARTEMIS_HOME property to the new directory created when the patch was extracted.

    ARTEMIS_HOME='/opt/redhat/jboss-amq-7.x.x-redhat-1'
  9. Restart the broker by entering the following command:

    BROKER_INSTANCE_DIR/bin/artemis run
  10. (Optional) Confirm that the broker is running and that the version has changed. After starting the broker, open the log file BROKER_INSTANCE_DIR/log/artemis.log and find two lines similar to the ones below. Note the new version number that appears in the log after the broker is live.

    INFO  [org.apache.activemq.artemis.core.server] AMQ221007: Server is now live
    ...
    INFO  [org.apache.activemq.artemis.core.server] AMQ221001: Apache ActiveMQ Artemis Message Broker version 2.1.0.amq-700005-redhat-1 [0.0.0.0, nodeID=4782d50d-47a2-11e7-a160-9801a793ea45]

Patching and Upgrading on Windows

Procedure

  1. Download the desired patch from the Red Hat Customer Support Portal by following the instructions provided in Downloading an AMQ Broker Archive.
  2. By using a file manager, move the patch to the directory folder your created during the original installation of AMQ Broker.
  3. Extract the file contents into the directory by right-clicking on the zip file and choosing Extract All.
  4. Stop the broker if it is running by entering the following command.

    BROKER_INSTANCE_DIR\bin\artemis-service.exe stop
  5. As a precaution, create a backup of the broker by creating a copy by using your a file manager.

    1. Right click on the BROKER_INSTANCE_DIR folder and select Copy.
    2. Next, right click in the same window and select Paste.
  6. (Optional) Note the current version of the broker. After the broker stops, a line similar to the one below is displayed at the end of the broker’s log file, which can be found at BROKER_INSTANCE_DIR\log\artemis.log.

    INFO  [org.apache.activemq.artemis.core.server] AMQ221002: Apache ActiveMQ Artemis Message Broker version 2.0.0.amq-700005-redhat-1 [4782d50d-47a2-11e7-a160-9801a793ea45] stopped, uptime 28 minutes
  7. Edit the BROKER_INSTANCE_DIR\etc\artemis.profile configuration file and set the ARTEMIS_HOME property to the new directory created when the patch was extracted.

    ARTEMIS_HOME='_INSTALL_DIR_\jboss-amq-7.x.x-redhat-1'
  8. Restart the broker entering the following command:

    BROKER_INSTANCE_DIR\bin\artemis-service.exe start
  9. (Optional) Confirm that the broker is running and that the version has changed. After starting the broker, open the log file BROKER_INSTANCE_DIR\log\artemis.log and find two lines similar to the ones below. Note the new version number that appears in the log after the broker is live.

    INFO  [org.apache.activemq.artemis.core.server] AMQ221007: Server is now live
    ...
    INFO  [org.apache.activemq.artemis.core.server] AMQ221001: Apache ActiveMQ Artemis Message Broker version 2.1.0.amq-700005-redhat-1 [0.0.0.0, nodeID=4782d50d-47a2-11e7-a160-9801a793ea45]