|
| |
| Sun Java Enterprise System 5 Update 1 Upgrade Guide for UNIX | |
Chapter 10
Message QueueThis chapter describes how to upgrade Message Queue software from previous Java ES versions to Java ES 5 Update 1 (Release 5U1): Sun Java System Message Queue 3.7 UR2. It covers both feature upgrades from previous Java ES release families and maintenance upgrades from Java ES 5.
The chapter provides an overview of upgrade considerations for the different upgrade paths supported by Release 5U1. The chapter covers upgrades on both the Solaris and Linux operating systems:
Overview of Message Queue UpgradesThis section describes the following general aspects of Message Queue that impact upgrading to Java ES 5 Update 1 (Release 5U1):
About Release 5U1 Message Queue
Release 5U1 Message Queue is a maintenance release that fixes bugs in Release 5 Message Queue. Release 5 Message Queue was a feature release that represented a minor upgrade with respect to Release 4.
Message Queue software has historically included two editions, a Platform Edition and an Enterprise Edition, each corresponding to a different feature set and licensed capacity. Enterprise Edition was for deploying and running messaging applications in an enterprise production environment. Platform Edition was mainly for developing, debugging, and load testing messaging applications and components. With Release 5 Message Queue, the Platform Edition was deprecated and Message Queue includes all Enterprise Edition features. An upgrade from an earlier Java ES release version to Release 5U1 converts any installed Platform Edition to full Message Queue enterprise-level features.
Message Queue Upgrade Roadmap
Table 10-2 shows the supported Message Queue upgrade paths to Release 5U1. The table applies to both Solaris and Linux operating systems.
Table 10-2 Upgrade Paths to Java ES 5 Update 1 (Release 5U1): Message Queue 3.7 UR2
Java ES Release
Message Queue Version
General Approach
Reconfiguration Required
Release 5
Sun Java System Message Queue
3.7 UR1Maintenance upgrade. Apply patches.
None
Release 4
Sun Java System Message Queue
2005Q4 (3.6 SP3))
Enterprise Edition onlyFeature upgrade. Direct upgrade using Java ES installer.
Data conversion performed automatically.
Release 3
Sun Java System Message Queue
2005Q1 (3.6)
Enterprise Edition onlyFeature upgrade. Direct upgrade using Java ES installer.
Data conversion performed automatically.
Release 2
Sun Java System Message Queue
2004Q2 (3.5 SP1)
Platform and Enterprise EditionsFeature upgrade. Direct upgrade performed using the mqupgrade script.
Performed automatically on Solaris platforms, and an mqmigrate script is available on Linux platforms.
Release 1
Sun Java System Message Queue
2003Q4 (3.0.1 SP2)
Platform and Enterprise EditionsFeature upgrade. Direct upgrade not certified, but can be performed using the mqupgrade script.1
Performed automatically on Solaris platforms, and an mqmigrate script is available on Linux platforms.
Pre-dates Java ES releases
Sun Java System Message Queue
3.0.x and earlier versions
Platform and Enterprise EditionsFeature upgrade. Direct upgrade not certified, but can be performed using Java ES installer.
1Back up and then restoration of the following files might be required before and after running the mqupgrade script: for example (on Solaris OS): restoring /etc/imq/passwd and /etc/imq/accesscontrol.properties to /var/imq/instances/instanceName/etc/
In addition to the Java ES releases of Message Queue shown in Table 10-2, Message Queue is also bundled with Solaris OS software. Upgrade of the bundled versions of Message Queue to Release 5U1 can be performed using the Java ES installer.
Message Queue Data
Message Queue, like other Java ES components, makes use of various kinds of data that for any specific upgrade might need to be migrated to an upgraded version. The following table shows the type of data that could be impacted by an upgrade of Message Queue software.
Table 10-3 shows the location of data on Solaris systems. The location on Linux systems is similar, but depends on the version of Message Queue:
For more information, see the Message Queue 3.7 UR1 Administration Guide, http://docs.sun.com/doc/819-4467/6n6k98brl?a=view.
In Table 10-3, instanceName identifies the name of the Message Queue broker instance with which the data is associated.
Message Queue Upgrade Strategy
Your strategy for upgrading Message Queue generally depends on the many issues discussed in Chapter 1, "Planning for Upgrades": upgrade path, dependencies between Java ES components, selective upgrade versus upgrade all, multi-instance deployments, and so forth.
This section is to particularize that general discussion to Message Queue by presenting issues that might influence your Message Queue upgrade plan.
Compatibility Issues
Release 5U1 Message Queue introduces no new incompatibilities over Release 3, Release 4, or Release 5. However, there are significant compatibility issues with respect to Release 2 and earlier versions. These are discussed in Release 2 Compatibility Issues.
In addition, as a general rule, if you mix Release 4 and earlier Message Queue brokers and Release 5 or 5U1 Message Queue brokers in a cluster, the master broker must be the earlier release broker, and the cluster will run as the earlier release Message Queue cluster.
Message Queue Dependencies
Message Queue dependencies on other Java ES components can impact the procedure for upgrading and re-configuring Message Queue software. Changes in Message Queue interfaces or functions, for example, could require upgraded version of components upon which Message Queue depends. The need to upgrade such components depends upon the specific upgrade path.
Message Queue has dependencies on the following Java ES components:
- Shared components. Message Queue has dependencies on specific Java ES shared components (see Table 1-10).
- Directory Server. Message Queue has an optional dependency on Directory Server: you can configure Message Queue to store administered objects and/or user data in an LDAP directory (Directory Server) rather than locally.
- Web Container. Message Queue has an optional dependency on Web Server, Application Server, or a third-party web container to support HTTP messaging between client and broker.
- Databases. Message Queue has an optional dependency on Java DB (or third-party databases) to provide JDBC-accessible data store, rather than a flat-file message store, for the Message Queue persistence layer.
- Sun Cluster. Message Queue has an optional dependency on Sun Cluster to provide high availability support.
Message Queue in an Application Server Environment
Message Queue is used to support the asynchronous message delivery capability of Application Server. There are a number of ways in which Application Server can manage Message Queue's support, and these impact how you shut down Message Queue brokers as part of the Message Queue upgrade procedure.
Application Server can be configured to manage Message Queue in the following ways:
- Local. Message Queue runs in a separate Java Virtual Machine from Application Server, but its life cycle is controlled by the Application Server instance. Message Queue is started by the Application Server, and though you can shut down the Message Queue broker independently, you will likely be unable to restart it properly. The Message Queue broker shuts down with the Application Server instance with which it is associated.
- Remote. Message Queue is not controlled by the Application Server at all. The Message Queue broker must be started before Application Server instance is started. The Message Queue broker can be independently shut down, but this impacts the Application Server instance.
In both these scenarios, you should shut down the Application Server instance with which a Message Queue broker is associated in order to perform a Message Queue upgrade.
Dual Upgrade
Dual upgrades, in which both Message Queue and operating system are upgraded (as described in Dual Upgrades: Java ES and Operating System Software) can be performed in either of two ways:
Fresh Operating System Installation
- Back up existing Message Queue data.
The essential data and its location is shown in Table 10-3.
- Install the new operating system.
The operating system installation can be on a new system (or a Solaris 10 zone) or it can wipe out the existing file system.
- Install Release 5U1 Message Queue.
- Restore or migrate the Message Queue data that was backed up in Step 1.
When upgrading from Release 2 Message Queue on Linux, the data is restored to the Release 5U1 location.
In-place Operating System Upgrade
- Back up existing Message Queue data.
The essential data and its location is shown in Table 10-3.
- Upgrade the operating system.
The upgrade leaves the existing file system in place.
- Upgrade to Release 5U1 Message Queue.
See the appropriate section of this chapter, depending on your upgrade path. the upgrade should leave the existing Message Queue data in tact.
When upgrading from Release 2 Message Queue on Linux, however, the data must be moved to the Release 5U1 location.
Upgrading Message Queue from Java ES 5This section includes information about upgrading Message Queue from Java ES 5 (Release 5) to Java ES 5 Update 1 (Release 5U1). The section covers the following topics:
Introduction
When upgrading Release 5 Message Queue to Release 5U1, consider the following aspects of the upgrade process:
- General Upgrade Approach. The upgrade is achieved by patching Release 5 Message Queue.
- Upgrade Dependencies. Message Queue has dependencies on a number of Java ES shared components (see Table 1-10), none of which need to be upgraded when you perform a maintenance upgrade of Message Queue.
- Backward Compatibility. Release 5UI Message Queue is backwardly compatible with the Release 5 version.
- Upgrade Rollback. A rollback of the Release 5U1 upgrade is achieved on Solaris OS by backing out the patch upgrade, but on the Linux platform rollback is achieved by manually reinstalling previous RPM packages.
- Platform Issues. The general approach for upgrading Message Queue is the same on both Solaris and Linux operating systems.
Release 5 Message Queue Upgrade
This section describes how to perform an upgrade of Message Queue from Java ES Release 5 to Release 5U1 on both the Solaris and Linux platform. Where a topic depends on platform-specific procedures, the topic will indicate the operating system to which it applies. The section covers the following topics:
Pre-Upgrade Tasks
Before you upgrade Message Queue software you should perform the following tasks:
Verify Current Version Information
You can determine the current version and edition of Message Queue installed on your system by starting the Message Queue broker with the -version option:
imqbrokerd -version
Upgrade Message Queue Dependencies
It is generally recommended that all Java ES components on a computer system (and in a computing environment) be upgraded to Release 5U1. Release 5U1 Message Queue has no hard upgrade dependencies, so upgrade of shared components is optional.
Back Up Message Queue Data
It is always a good practice to back up application data in a production environment before performing an upgrade. The essential data and its location is shown in Table 10-3.
Upgrading Release 5 Message Queue (Solaris)
This section discusses considerations that impact the upgrade procedure for Message Queue, followed by a description of the procedure itself.
Upgrade Considerations (Solaris)
The upgrade of Message Queue software to Java ES Release 5U1 takes into account the following considerations:
- In a deployment architecture in which there are multiple instances of Message Queue running on a single computer (all corresponding to the same installed Message Queue image), you only have to upgrade the Message Queue image once.
- In a maintenance upgrade, you do not have to migrate schema, configuration, security or user data.
- The Release 5U1 Message Queue upgrade patches for Solaris OS are shown in the following table:
Table 10-5 Patches1 to Upgrade Message Queue on Solaris
Description
Patch ID: SPARC
Solaris 9 & 10
Patch ID: X86
Solaris 9 & 10
Message Queue Core
125060-03
125062-03
Message Queue C-API
125061-03
125063-03
1Patch revision numbers are the minimum required for upgrade to Release 5U1. If newer revisions become available, use the newer ones instead of those shown in the table.
Upgrade Procedure (Solaris)
The procedure documented below applies to Message Queue instances residing locally on the computer where the upgrade is taking place.
- Log in as root or become superuser.
su -
- Stop any running Release 5 Message Queue brokers.
If Message Queue is supporting an Application Server instance, see Message Queue in an Application Server Environment. For an independent Message Queue broker use the following command:
imqcmd shutdown bkr [-b hostName:port]
You will be prompted for the admin user name and password.
- Obtain the latest Message Queue upgrade patches, based on Table 10-5.
To obtain the patch, see Accessing Java ES Patches. Patches can be downloaded to /workingDirectory.
- Apply the appropriate Message Queue core and, if needed, localization patches in Table 10-5, in that order.
patchadd /workingDirectory/patch_ID
Be sure to consult the README.patch_ID file for additional patch installation instructions.
- Confirm that the patch upgrades were successful:
showrev -p | grep patch_ID
The output should return the versions of patch IDs applied in Step 4.
- Start the Release 5U1 Message Queue brokers.
imqbrokerd -name instanceName
Upgrading Release 5 Message Queue (Linux)
This section discusses considerations that impact the upgrade procedure for Message Queue, followed by a description of the procedure itself.
Upgrade Considerations (Linux)
The upgrade of Message Queue software to Java ES Release 5U1 on the Linux platform takes into account the same considerations as on the Solaris platform (see Upgrade Considerations (Solaris)), except that the Linux Release 5U1 upgrade patches differ from the Solaris patches.
The Release 5U1 Message Queue upgrade patches for Linux OS are shown in the following table:
Table 10-6 Patches1 to Upgrade Message Queue on Linux
Description
Patch ID and RPM names
Message Queue Core and C-API
125064-03
1Patch revision numbers are the minimum required for upgrade to Release 5U1. If newer revisions become available, use the newer ones instead of those shown in the table.
Upgrade Procedure (Linux)
The procedure documented below applies to Message Queue instances residing locally on the computer where the upgrade is taking place.
- Log in as root or become superuser.
su -
- Stop any running Release 5 Message Queue brokers.
If Message Queue is supporting an Application Server instance, see Message Queue in an Application Server Environment. For an independent Message Queue broker use the following command:
imqcmd shutdown bkr [-b hostName:port]
You will be prompted for the admin user name and password.
- Obtain the latest Message Queue upgrade patches, based on Table 10-6.
To obtain the patch, see Accessing Java ES Patches. Patches can be downloaded to /workingDirectory.
- Apply the core and, if needed, localization patch for Message Queue in Table 10-6, in that order.
cd /workingDirectory/patch_ID
./installpatchIf installpatch reports any errors, you will need to resolve the reported errors and run installpatch again.
Be sure to consult the README.patch_ID file for additional patch installation instructions.
- Confirm that the patch upgrades were successful.
rpm -qa | grep sun-mq
The new version numbers of the RPMs should be returned.
- Start the Release 5U1 Message Queue brokers.
imqbrokerd -name instanceName
Verifying the Upgrade
You can verify successful upgrade of Message Queue by starting the Message Queue broker with the -version option.
The command returns the Message Queue-specific version number. See Table 10-4 for output values.
Post-Upgrade Tasks
There are no post-upgrade tasks beyond the steps described in Upgrade Procedure (Solaris) and Upgrade Considerations (Linux).
Rolling Back the Upgrade (Solaris)
This section describes the Release 5U1 upgrade rollback procedure for Message Queue on the Solaris platform.
- Log in as root or become superuser.
su -
- Stop any running Message Queue brokers.
If Message Queue is supporting an Application Server instance, see Message Queue in an Application Server Environment. For an independent Message Queue broker use the following command:
imqcmd shutdown bkr [-b hostName:port]
You will be prompted for the admin user name and password.
- Remove the patches in Table 10-5.
patchrm patch_ID
- Restore data you backed up before performing the upgrade.
See Back Up Message Queue Data.
- Restart the Message Queue brokers that were stopped in Step 2.
imqbrokerd -name instanceName
Rolling Back the Upgrade (Linux)
This section describes the Release 5U1 upgrade rollback procedure for Message Queue on the Linux platform. There is no automated rollback procedure for Linux patches, so the recommended approach is to manually overwrite the Release 5U1 RPMs with the Release 5 RPMs, as described below.
- Log in as root or become superuser.
su -
- Stop any running Message Queue brokers.
If Message Queue is supporting an Application Server instance, see Message Queue in an Application Server Environment. For an independent Message Queue broker use the following command:
imqcmd shutdown bkr [-b hostName:port]
You will be prompted for the admin user name and password.
- Check the revision numbers of Message Queue RPMs.
rpm -qa | grep sun-mq
The updated RPMs should be those listed in Table 10-6.
- Check to see if the RPMs have been relocated from their default location.
rpm -q --queryformat '%{INSTALLPREFIX}' rpmName
where rpmName is the unique name of the RPM (for example, the values sun-mq-* shown in Table 10-6). The command returns a prefixValue as a path to the installed RPM.
- Reinstall Release 5 RPMs from the Java ES 5 distribution.
(If you are rolling back to a post-Release 5 sustaining patch, rather than to Release 5, reinstall the RPMs from that patch.)
rpm -Uvh --force [--prefix prefixValue] *.rpm
The --force option will allow the command to overwrite later packages of the same name. The --prefix option is not required unless the RPMs have been relocated. (If only a subset of the RPMs had been relocated, use individual file names as command arguments rather than *.rpm.)
- Restore data you backed up before performing the upgrade.
See Back Up Message Queue Data.
- Restart the Message Queue brokers that were stopped in Step 2.
imqbrokerd -name instanceName
Multiple Instance Upgrades
To upgrade a Message Queue cluster, in which multiple brokers interact to provide a scalable message service, you can do a rolling upgrade in which the cluster remains online as each Message Queue instance is upgraded from Release 5 to Release 5U1. Keep the following in mind when performing a cluster upgrade:
Otherwise the procedure is straightforward: you shut down, upgrade, and restart the brokers one at a time until all have been upgraded.
Upgrading Message Queue from Java ES Release 4This section includes information about upgrading Message Queue from Java ES 2005Q4 (Release 4) to Java ES 5 Update 1 (Release 5U1). The section covers the following topics:
Introduction
When upgrading Java ES Release 4 Message Queue to Release 5U1, consider the following aspects of the upgrade process:
- General Upgrade Approach. The upgrade is performed using the Java ES installer. The installer migrates configuration data from Release 4 automatically. In addition, any dynamic application data associated with Release 4 will be converted automatically the first time imqbrokerd is run. For a file-based store, this means the contents of the fs350 directory will be copied to a new fs370 directory. For a JDBC store, a simple version update will occur to the existing database tables.
- Upgrade Dependencies. Message Queue has dependencies on a number of Java ES shared components (see Table 1-10), all of which are automatically upgraded to Release 5U1 by the Java ES installer when you perform an upgrade of Message Queue.
In addition, Release 5U1 Message Queue has dependencies on Java ES product components, as described in Message Queue Dependencies. However, upgrade of these components is not required to upgrade Message Queue to Release 5U1.
- Backward Compatibility. Release 5U1 Message Queue is fully compatible with Release 4, with respect to protocols, broker compatibility, administered objects, administration tools, and client applications.
- Upgrade Rollback. There is no utility for rolling back the Message Queue upgrade to Release 4. You have to remove the upgraded components and manually restore the previous version and configuration data.
- Platform Issues. The approach for upgrading Message Queue is the same on both Solaris and Linux operating systems.
Release 4 Message Queue Upgrade
This section describes how to perform a Message Queue upgrade from Java ES Release 4 to Release 5U1:
Pre-Upgrade Tasks
Before you upgrade Message Queue software you should perform the following tasks:
Verify Current Version Information
You can determine the version and edition of Message Queue installed on your system by starting the Message Queue broker with the -version option:
imqbrokerd -version
Upgrade Message Queue Dependencies
It is generally recommended that all Java ES components on a computer system (and in a computing environment) be upgraded to Release 5U1. Message Queue has hard upgrade dependencies on only a couple of shared components.
When upgrading Message Queue dependencies, you should do so in the order below (skipping any that might already have been upgraded), before you upgrade Message Queue. Upgrade of shared components is achieved automatically by the Java ES installer.
- Shared Components. Instructions for synchronizing Java ES shared components to Release 5U1 are provided in Upgrading Java ES Shared Components. However, all shared components required by Message Queue are upgraded automatically by the Java ES installer when you perform an upgrade of Message Queue to Release 5U1.
- Sun Cluster (soft upgrade dependency). Instructions for upgrading Sun Cluster to Release 5U1 are provided in Chapter 3, "Sun Cluster Software".
- Directory Server (soft upgrade dependency). Instructions for upgrading Directory Server to Release 5U1 are provided in Chapter 5, "Directory Server".
- Java DB (soft upgrade dependency). You need to perform a fresh install of Release 5U1 Java DB when upgrading Message Queue.
- Web Container Software (soft upgrade dependency). Instructions for upgrading Web Server or Application Server are provided in Chapter 7, "Web Server" on page 173 and Chapter 11, "Application Server", respectively.
Back Up Message Queue Data
It is always a good practice to back up application data in a production environment before performing an upgrade. The essential data and its location is shown in Table 10-3.
Upgrading Release 4 Message Queue
The upgrade procedure consists of the following steps:
- Stop any running Message Queue client applications.
If Message Queue is being used in an Application Server environment, shut down Application Server, as well.
- Stop any running Message Queue brokers.
If Message Queue is supporting an Application Server instance, see Message Queue in an Application Server Environment. For an independent Message Queue broker use the following command:
imqcmd shutdown bkr [-b hostName:port]
You will be prompted for the admin user name and password.
- If you do not want to preserve dynamic data, the Message Queue flat-file user repository, and the Message Queue access control file associated with each broker instance, remove this data using the following command.
imqbrokerd -name instanceName -remove instance
Otherwise, dynamic data and configuration information will be retained and used for Release 5U1 Message Queue.
- Log in as Root.
su -
- Launch the Java ES installer.
cd Java ES Release 5U1 distribution/os_arch
./installerwhere os_arch matches your platform, such as Solaris_sparc. (Use the installer -nodisplay option for the command line interface.)
After the Welcome and License Agreement pages are displayed, you will be presented with a component selection page. (When installed components are detected that can be directly upgraded by the Java ES installer, they are shown with a status of "upgradable.")
- Select Message Queue in the component selection page.
- Confirm your upgrade choice.
Message Queue packages will be upgraded and an upgrade summary displayed.
- Exit the Java ES installer.
- Apply the latest Message Queue maintenance patches, if any.
- Check if there have been any Message Queue point fixes subsequent to Release 5U1.
Periodically obtain the latest patches as described in Accessing Java ES Patches and compare them to the Release 5U1 patch revision numbers shown in Table 10-5 (Solaris) or Table 10-6 (Linux).
If you are using Sun Connection on the Solaris platform, you are automatically notified of new patches for Java ES components installed on your computer.
- Apply the appropriate Message Queue core and, if needed, localization patches in that order.
On Solaris:
patchadd /workingDirectory/patch_IDIf you are using the accumulated patch cluster on the Solaris platform, the install_cluster script will apply any Java ES patches needed on your computer.
On Linux:
cd /workingDirectory/patch_ID
./installpatchBe sure to consult the README.patch_ID file for additional patch installation instructions.
- Confirm that the patch upgrades were successful:
On Solaris:
showrev -p | grep patch_IDOn Linux:
rpm -qa | grep sun-mqThe output should return the appropriate patch IDs or revision numbers.
Verifying the Message Queue Upgrade
You can verify successful upgrade of Message Queue by starting the Message Queue broker with the -version option.
The command returns the Java ES version number as well as the Message Queue-specific version number. See the version verification outputs in Table 10-4.
Post-Upgrade Tasks
If you have upgraded the web container and are using the Message Queue HTTP tunneling servelet, you may need to re-deploy it in the new web container. There has been no change to the HTTP tunneling servlet between Release 4 and Release 5U1. For more information on HTTP support, see the Message Queue 3.7 UR1 Administration Guide, http://docs.sun.com/doc/819-4467.
Also, if you are sure you will not need to roll back the upgrade, you can remove the Release 4 file-based data store located in the fs350 directory (see Table 10-3).
Rolling Back the Upgrade
No scripts are provided for rolling back Message Queue to its pre-upgrade state. The process must be performed manually using the following steps:
- Stop any running Message Queue client applications.
- Stop any running Message Queue brokers.
If Message Queue is supporting an Application Server instance, see Message Queue in an Application Server Environment. For an independent Message Queue broker use the following command:
imqcmd shutdown bkr [-b hostName:port]
You will be prompted for the admin user name and password.
- If you want to delete dynamic data, the Message Queue flat-file user repository, and the Message Queue access control file associated with each broker instance, remove this data using the following command.
imqbrokerd -name instanceName -remove instance
- Log in as root or become superuser.
su -
- Retrieve the list of installed Message Queue packages with the following command:
On Solaris:
pkginfo | grep -i "message queue"On Linux:
rpm -qa | grep sun-mq- Remove the Message Queue packages, using the following command:
On Solaris:
pkgrm packageName
where packageName is any of the Message Queue packages. To remove multiple packages, separate the package names by a space.On Linux:
rpm -e --nodeps RPMName
where RPMName is any of the Message Queue RPM packages. To remove multiple packages, separate the RPM names by a space.Because other products might be using Message Queue packages, be careful about removing them. The Solaris pkgrm command will warn you of any dependencies on a package before removing it. When prompted, confirm your removal request by typing y (yes).
- Type "q" to quit.
- Exit the root shell.
- Re-install Release 4 Message Queue.
Use the Java ES Release 4 installer.
- Restore Release 4 Message Queue data backed up in Back Up Message Queue Data.
Release 4 Message Queue will work fine with data backed up before the upgrade to Release 5U1.
Multiple Instance Upgrades
To upgrade a Message Queue cluster, in which multiple brokers interact to provide a scalable message service, you can do a rolling upgrade in which the cluster remains online as each Message Queue instance is upgraded from Release 4 to Release 5U1. The two conditions to keep in mind when performing a cluster upgrade are:
Otherwise the procedure is straightforward: you shut down, upgrade, and restart the brokers one at a time until all have been upgraded.
Upgrading Message Queue from Java ES Release 3The procedure for upgrading Java ES 2005Q1 (Release 3) Message Queue to Release 5U1 is the same as that for upgrading Release 4 Message Queue to Release 5U1.
To upgrade Release 3 Message Queue to Release 5U1, use the instructions in Upgrading Message Queue from Java ES Release 4, except substitute Release 3 wherever Release 4 is referenced.
Upgrading Message Queue from Java ES Release 2Java ES certifies indirect upgrade from Java ES 2004Q2 (Release 2) Message Queue by first upgrading to Release 5 Message Queue (as documented in the Java Enterprise System 5 Update 1 Upgrade Guide for UNIX, http://docs.sun.com/doc/819-6553) and then upgrading from Release 5 Message Queue to Release 5U1 Message Queue (as documented in Upgrading Message Queue from Java ES 5).
However, direct upgrade is also supported. This section includes information about direct upgrade of Message Queue from Java ES 2004Q2 (Release 2) to Release 5U1. The section covers the following topics:
Note
If you are upgrading from Release 2 Message Queue on the Linux platform, then you will have to perform a dual upgrade, in which both Message Queue and the operating system are upgraded (Release 5U1 Message Queue is not supported on RHEL 2.1). See Dual Upgrade for more information.
Introduction
When upgrading Java ES Release 2 Message Queue to Release 5U1, consider the following aspects of the upgrade process:
- General Upgrade Approach. The upgrade is performed using an mqupgrade script that replaces previous software packages with new ones and migrates configuration data from Release 2 automatically.
- Upgrade Dependencies. Upgrade of any Java ES component on a computer from Release 2 requires the upgrade of all other Java ES components hosted by the computer; selective upgrade of Java ES components from Release 2 to Release 5U1 is not supported. In particular, all Java ES shared components used by Message Queue need to be upgraded.
In addition, Release 5U1 Message Queue is optionally dependent on Directory Server and Web Server (or Application Server), as described in Message Queue Dependencies. If these are installed on the same computer, upgrade of these components to Release 5U1 is also required.
- Backward Compatibility. Release 5U1 Message Queue is not fully compatible with Release 2, as described in Release 2 Compatibility Issues, below.
- Upgrade Rollback. Rollback from Release 5U1 to Release 2 is not currently supported (see Rolling Back the Upgrade).
- Platform Issues. The general approach for upgrading Message Queue is the same on both Solaris and Linux operating systems, however there are some additional procedures required on Linux. The procedures that follow indicate platform-specific commands, file locations, or procedures where appropriate.
Release 2 Compatibility Issues
Release 5 Message Queue introduced the following general Message Queue compatibility issues with respect to Release 2 and earlier versions. These issues apply to Release 5U1 as well.
Protocol Compatibility
Message Queue has a dependency on a web container to provide HTTP protocol support between Message Queue clients and broker. Due to a protocol change, when using Sun Java System Web Server to provide a web container for the Message Queue imqhttp.war application, you cannot upgrade the Web Server component without also upgrading Message Queue (see Post-Upgrade Tasks on (more...) and (more...) .
Broker Compatibility
A Release 5 Message Queue broker will inter-operate with a Release 4, Release 3, or Release 2 broker, however changes in broker properties and the persistent store schema with respect to Release 2 can impact compatibility.
Release 5 Message Queue can use Release 4, Release 3, and Release 2 data, except that on Linux systems, Release 2 data must be first migrated to Release 5.
When updating to Release 5 Message Queue, consider the following:
- You can use earlier Message Queue config.properties files. You can also copy them to another location and consult the property settings they contain when you configure Release 5 Message Queue brokers.
- Any persistent Message Queue data—messages, destinations, durable subscriptions—is automatically converted, if necessary, to Release 5 Message Queue data when starting up a broker for the first time. For example, any existing destinations will be converted, if necessary, to Release 5 Message Queue destinations, preserving existing attributes and using default values of new attributes.
- If you mix Message Queue Release 2 brokers and Message Queue Release 5 brokers in a cluster, the master broker must be a Message Queue Release 2 broker (whichever is older), and the cluster will run as a Message Queue Release 2 cluster.
Administered Object Compatibility
Release 5 Message Queue administered objects are identical to Release 3 and Release 4 administered objects. However, some Release 3 administered objects were renamed or enhanced with new attributes with respect to earlier versions. Therefore, when upgrading from Release 2 Message Queue to Release 5, you should consider the following:
- You can use the same object store and administered objects that you created in Release 2; however, it is best to migrate your administered objects to Release 5. The Administration Console (imqadmin) and the ObjectManager command line utility (imqobjmgr), when performing an update operation, will convert Release 2 administered objects into Release 5 administered objects.
- The Release 5 client runtime will look up and instantiate Release 2 administered objects and convert them for use by Release 5 clients. However, this will not convert Release 2 administered objects residing in the object store from which the lookup was made.
- Existing Release 2 clients (applications and/or components)—that is, clients that directly instantiate administered objects rather than look them up—are compatible with Release 5. However, if they are to use the new administered object attributes (see Chapter 16 of the Message Queue 3.7 UR1 Administration Guide, http://docs.sun.com/doc/819-4467 for information on administered object attributes), they will need to be rewritten. (Re-compiling Release 2 clients with Release 5 will show which Message Queue Release 2 attributes have been renamed in Release 5. The old names will still work.)
- Scripts that start Java clients and which set administered object attribute values using command line options are compatible with Release 5. However, if they are to use the new administered object attributes (see Chapter 16 of the Message Queue 3.7 UR1 Administration Guide, http://docs.sun.com/doc/819-4467 for information on administered object attributes), they will need to be rewritten.
Administration Tool Compatibility
Because of the addition of new commands and new administrative capabilities in Release 3, the Release 5 administration tools (the Administration Console and command line utilities) only work with Release 3, Release 4, and Release 5 brokers. However, all Release 2 commands and command options remain supported.
Client Compatibility
Release 3 and Release 4 clients are completely compatible with Release 5 Message Queue. When upgrading from Release 2 to Release 5, however, you should consider the following compatibility issues, regarding Java clients:
- A Release 5 broker will support a Release 2 client (but without additional Release 5 capabilities).
- A Release 5 Java client can connect to a Release 2 broker (but without additional Release 5 capabilities).
- C client programs are supported by Release 5 and by Release 2, Release 3, or Release 4 brokers running with an Enterprise Edition license or a Platform Edition trial license.
Release 2 Message Queue Upgrade
This section describes how to perform a Message Queue upgrade from Java ES Release 2 to Release 5U1:
Pre-Upgrade Tasks
Before you upgrade Message Queue software you should perform the following tasks:
Verify Current Version Information
You can determine the version and edition of Message Queue installed on your system by starting the Message Queue broker with the -version option:
imqbrokerd -version
Upgrade Message Queue Dependencies
It is generally recommended that all Java ES components on a computer system (and in a computing environment) be upgraded to Release 5U1. Message Queue has hard upgrade dependencies on only a couple of shared components.
When upgrading Message Queue dependencies, you should do so in the order below (skipping any that might already have been upgraded), before you upgrade Message Queue.
- Shared Components. Instructions for upgrading Java ES shared components to Release 5U1 are provided in Chapter 2, "Upgrading Java ES Shared Components").
- Sun Cluster (soft upgrade dependency). Instructions for upgrading Sun Cluster to Release 5U1 are provided in Chapter 3, "Sun Cluster Software".
- Directory Server (soft upgrade dependency). Instructions for upgrading Directory Server to Release 5U1 are provided in Chapter 5, "Directory Server".
- Java DB (soft upgrade dependency). You need to perform a fresh install of Release 5U1 Java DB when upgrading Message Queue.
- Web Container Software (soft upgrade dependency). Instructions for upgrading Web Server or Application Server are provided in Chapter 7, "Web Server" on page 173 and Chapter 11, "Application Server", respectively.
Back Up Message Queue Data
It is always a good practice to back up application data in a production environment before performing an upgrade. The essential data and its location is shown in Table 10-3.
Upgrading Release 2 Message Queue (Solaris)
The upgrade of Message Queue software to Release 5U1 makes use of the mqupgrade script, which installs Release 5U1 packages.
The upgrade procedure consists of the following steps:
- Stop any running Message Queue client applications.
If Message Queue is being used in an Application Server environment, shut down Application Server, as well.
- Stop any running Message Queue brokers.
If Message Queue is supporting an Application Server instance, see Message Queue in an Application Server Environment. For an independent Message Queue broker use the following command:
imqcmd shutdown bkr [-b hostName:port]
You will be prompted for the admin user name and password.
- If you do not want to preserve dynamic data, the Message Queue flat-file user repository, and the Message Queue access control file associated with each broker instance, remove this data using the following command.
imqbrokerd -name instanceName -remove instance
Otherwise, dynamic data and configuration information will be retained and used for Release 5U1 Message Queue.
- Log in as Root.
su -
- Change directories to the location of the Tools directory of the Java ES Release 5U1 distribution.
On Solaris SPARC:
cd Solaris_sparc/Product/message_queue/ToolsOn Solaris x86:
cd Solaris_x86/Product/message_queue/Tools- Run the mqupgrade script.
- Start the script:
./mqupgrade
The mqupgrade script lists installed Message Queue components.
- Enter y (yes) to upgrade Message Queue components.
The mqupgrade script detects and lists installed localization files.
If you do not want to upgrade Message Queue components, enter n (no). The mqupgrade script will exit without upgrading Message Queue components.
- If prompted, enter y (yes) to upgrade localization files.
The mqupgrade script sends output to a log file in the following location:
/var/sadm/install/logs/Message_Queue_upgrade_'date'.log
Upgrading Release 2 Message Queue (Linux)
The upgrade of Release 2 Message Queue to Release 5U1 on the Linux platform is complicated by the fact that Java ES Release 2 is supported only on RHEL 2.1, but Java ES 5 Update1 is not supported on RHEL 2.1. Hence a dual upgrade is required: both the operating system and Message Queue must be upgraded. See Dual Upgrades: Java ES and Operating System Software
The basic procedure is to upgrade the Linux OS first, then upgrade all the Message Queue dependencies, and then upgrade Message Queue.
The upgrade from Release 2 Message Queue to Release 5U1 includes a data migration step that is not needed on Solaris systems, namely the migration of broker instance data to the appropriate Release 5U1 location. If you want to preserve your Release 2 data in upgrading to Release 5U1, Message Queue provides a migration tool, mqmigrate, to perform this migration.
To upgrade from Release 2 to Release 5U1, you use the same instructions as used in Upgrading Release 2 Message Queue (Solaris), except you run the mqmigrate script (Step 6) before you run the mqupgrade script (Step 7), as detailed in the following procedure.
- Stop any running Message Queue client applications.
- Stop any running Message Queue brokers.
If Message Queue is supporting an Application Server instance, see Message Queue in an Application Server Environment. For an independent Message Queue broker use the following command:
imqcmd shutdown bkr [-b hostName:port]
You will be prompted for the admin user name and password.
- If you do not want to preserve dynamic data, the Message Queue flat-file user repository, and the Message Queue access control file associated with each broker instance, remove this data using the following command.
imqbrokerd -name instanceName -remove instance
Otherwise, dynamic data and configuration information will be retained and used for Release 5U1 Message Queue.
- Log in as root or become superuser.
su -
- Change directories to the location Tools directory of the Java ES Release 5 Update 1 distribution.
cd Linux_x86/Product/message_queue/Tools
- Migrate broker instance data using the following command:
./mqmigrate
The mqmigrate script will move Release 2 broker instance configuration data to the appropriate R4 location.
- Run the mqupgrade script.
- Start the script:
./mqupgrade
The mqupgrade script lists installed Message Queue components.
- Enter y (yes) to upgrade Message Queue components.
The mqupgrade script detects and lists installed localization files.
If you do not want to upgrade Message Queue components, enter n (no). The mqupgrade script will exit without upgrading Message Queue components.
- If prompted, enter y (yes) to upgrade localization files.
The mqupgrade script sends output to a log file in the following location:
/var/sadm/install/logs/Message_Queue_upgrade_'date'.log
Installing the Compatibility Package (Linux)
If you have scripts or your Release 2 client applications contain scripts that depend on the location of Release 5U1 installed files, you will need to install the sun-mq-compat package, which contains symlinks from Release 2 file locations to Release 5U1 file locations.
The sun-mq-compat package is in the following location where you unzipped the Java ES 5 Update 1 distribution.
Linux_x86/Product/message_queue/Packages
Perform the following steps to Install the sun-mq-compat Package:
Verifying the Message Queue Upgrade
You can verify successful upgrade of Message Queue by starting the Message Queue broker with the -version option.
The command returns the Java ES version number as well as the Message Queue-specific version number. See Table 10-4 for output values.
Post-Upgrade Tasks
If you are using the HTTP tunneling servlet to provide HTTP connection service support, the upgrade of Message Queue from Release 2 to Release 5U1 has upgraded the servlet. This requires you to re-deploy it after upgrading Message Queue to Release 5U1. See the Message Queue 3.7 UR1 Administration Guide, http://docs.sun.com/doc/819-4467 for more information on HTTP support.
Also, you have to migrate Release 2 administered objects to their Release 5U1 versions using the Administration Console (imqadmin) and/or the ObjectManager command line utility (imqobjmgr) to perform an update operation.
Rolling Back the Upgrade
The upgrade of Message Queue from Release 2 to Release 5U1 is not currently supported. Normally the procedure would be similar to the rollback from Release 5U1 to Release 4 (see Rolling Back the Upgrade). However, because the upgrade of Message Queue from Release 2 to Release 5U1 does not update the Java ES product registry, the Java ES installer cannot re-install Release 2 Message Queue.
For work-arounds to this problem, please consult Sun Services.
Multiple Instance Upgrades
To upgrade a Message Queue cluster, in which multiple brokers interact to provide a scalable message service, you can do a rolling upgrade in which the cluster remains online as each Message Queue instance is upgraded from Release 2 to Release 5U1. The two conditions to keep in mind when performing a cluster upgrade are:
Otherwise the procedure is straightforward: you shut down, upgrade, and restart the brokers one at a time until all have been upgraded.