Sun Java System Message Queue 3.7 UR1 Installation Guide

Chapter 3 Linux Installation

This chapter covers the following topics as they apply to a Linux installation of Message Queue 3.7 UR1:

Hardware and Software Requirements

In order to install Message Queue 3.7 UR1, your Linux system should satisfy the minimum hardware and software requirements shown in Table 3–1.

Table 3–1 Hardware and Software Requirements (Linux)


Component	Requirements
CPU	Intel Pentium 2 (or compatible)
RAM	256 MB
Disk space	Compressed installation (`.zip`) file: Approximately 18 MB Installed product: Approximately 18 MB Note – The installed product may require more space if the broker stores persistent messages locally.
Operating system	Red Hat Advanced Server 3.0, Update 6 Red Hat Advanced Server 4.0, Update 2
Java 2 Platform, Standard Edition (J2SE)	See Supported Platforms and Components for supported versions of the Java Runtime Environment (JRE) and Java Software Development Kit (JDK). Note – The Message Queue 3.7 UR1 software distribution includes the required JRE version at the time of release.

Installing Message Queue

The Message Queue 3.7 UR1 product can be downloaded from the Sun Java System Web site. Message Queue also depends on components that you must install in order to develop and run Message Queue clients. See Table 1–1 and Table 1–2 for more information.

Finding and Removing Earlier Message Queue Versions

Because Message Queue is installed with other products (such as Sun Java System Application Server), you should check whether an earlier version has already been installed on your system and, if so, uninstall it before installing Message Queue 3.7 UR1.

Migrating Files from an Earlier Installation

If Message Queue Version 3.0.x or 3.5 is already installed on your system and you want to preserve any of its instance data files (flat-file user repository, access control properties file, or password file), you will need to use the mqmigrate utility to migrate those files before uninstalling the earlier version of Message Queue. If you do not want to preserve your old data files, there is no need to run the mqmigrate utility.

Before you run the mqmigrate utility, you must be root.

su root

When prompted, enter your root password.

The mqmigrate utility assumes that the data files to be migrated are located in the standard directories shown in Table 3–2. In Message Queue 3.0.x installations, the base directory baseDir is assumed by default to be /opt, but the files may be installed in another, nonstandard base directory instead. The mqmigrate command provides an option, -basedir, for designating an alternate base directory from which to migrate the files:

./mqmigrate [-basedir baseDir]

For example, if the earlier installation's data files reside in a directory named, /export, you would migrate them with the command

./mqmigrate -basedir /export

Table 3–2 Message Queue Standard Data Directories


Message Queue Version	Standard Data Directories
3.0.`x`	`baseDir/imq/var` `baseDir/imq/etc`
3.5	`/var/opt/imq` `/etc/opt/imq`
3.6	`/var/opt/sun/mq` `/etc/opt/sun/mq`
3.7 UR1	`/var/opt/sun/mq` `/etc/opt/sun/mq`

Removing an Earlier Installation

Depending on the version, Message Queue might have been installed using either .tar files or the Red Hat Package Manager (RPM). You must therefore check for both of these installation methods. It is recommended that you check first for RPM installations and then for .tar file installations.

To Find and Remove Earlier RPM-Installed Versions of Message Queue

Check your system for an existing Message Queue installation.

Enter the command

imqbrokerd -version

If an earlier version of Message Queue is already installed, the version number is displayed.
- If no previous Message Queue installation is present, you can proceed to install Message Queue 3.7 UR1, as described in Installation Procedure.
- If you do find an existing Message Queue installation, go on to the next step.

Become root.

su root

Enter you root password.

(Optional) Migrate data files from the existing installation.

If the existing installation is of Message Queue Version 3.5 or earlier and you want to preserve its existing data files, use the command

./mqmigrate

to migrate the installation's broker configuration files, persistent data, and security-related files to their proper locations for your planned Message Queue 3.7 UR1 installation. (This step is not necessary if the existing installation is of Message Queue 3.6 or later.)

Note –
If you are migrating from a Message Queue 3.0.x installation located in a base directory other than the default (/opt), use the mqmigrate command's -basedir option to specify the alternate base directory. For example, if the existing installation resides in a base directory named /export, use the following command to migrate its data files.

./mqmigrate -basedir /export

If you do not know the correct base directory, you can find it by searching for the Message Queue imqbrokerd executable and noting its root installation directory.

Remove the existing Message Queue installed software.

Issue the following command(s) in the following order:
- For Message Queue Version 3.5 or earlier:
  
  rpm -e imq-ent
  
  rpm -e imq
- For Message Queue version 3.6 or 3.7:
  
  List Message Queue installed packages using the following command.
  
  rpm -qa | grep mq
Remove listed packages using the following syntax:

rpm -e pack1 [[,pack2]...]

To Find and Remove Earlier Tar-Based Installed Message Queue

See if the default Message Queue installation directory (/opt/imq/bin) exists on your system.

If not found, Message Queue might have been installed in a non-default location. If you cannot remember the installation directory, search for the Message Queue imqbrokerd executable and note its root install directory.

If there is no previous Message Queue installation, proceed to install Message Queue by following the directions in Installation Procedure.

If you find an earlier Message Queue installation in the default location (/opt/imq/bin), remove it as follows:
1. If you want to preserve existing broker instance data, run the mqmigrate utility (in the Message Queue 3.7 UR1 distribution) as described in Migrating Files from an Earlier Installation.
  
  The mqmigrate utility moves existing broker instance data (broker configuration files and persistent data) and security-related files, to new Message Queue 3.7 UR1 locations.
2. Remove the /opt/imq/ directory and all its contents.
  
  rm -rf /opt/imq

Installation Procedure

The following instructions explain how to download and install the Message Queue product on Linux from the Sun Java System Web site.

To Install Message Queue on Linux

Accept the license agreement on the Message Queue product download site.

Download the Message Queue product distribution file from the Web site into an empty, temporary download directory, temp_directory.

The download file is: mq3_7-ent-linx86.zip

Change to the temp_directory and uncompress the distribution file.

unzip mq3_7-ent-linx86.zip

The unzip command creates an mq3_7-ent directory, which contains the distribution files: LICENSE, README, and COPYRIGHT files; mqinstall utility; mquninstall utility; mqmigrate utility; and an rpms directory.

The following table describes the Message Queue RPM packages in the rpms directory. If any of these files already exist on your system, you need to check whether the version number is greater than that provided by Message Queue. If it is, you should do a custom install.

RPM	Description	Notes
`sun-mq-config`	`/etc` files
`sun-mq-var`	`/var` files
`sun-mq`	`/opt` files for the Message Queue Core RPM	Depends on the files `sun-javahelp` `sun-mq-jmsclient` `sun-mq-config` `sun-mq-var`
`sun-mq-jaxm`	Message Queue Java API for XML Messaging (JAXM): API	Depends on `sun-saaj.`
`sun-mq-jmsclient`	JMS: API and runtime	No dependencies
`sun-mq-xmlclient`	XML Client	Depends on `sun-jmsclient` and `sun-saaj.`
`sun-mq-capi`	C-API	Depends on `sun-nspr`, `sun-nss.`
`sun-mq-compat`	Symlinks to 3.5 locations.	Depends on `sun-mq`. Not installed by default. Use if your existing client applications contain scripts that depend upon former file locations (such as jar files).
`sun-mq-[locale]`	L10N files	No dependencies.
`sun-mq-len`	Legacy Enterprise license file.	No longer used.
`sun-javahelp` [This package is shared by a number of Sun Java System products. This package is not installed by default. You must manually install any shared packages after installing Message Queue packages.]	JavaHelp: API and runtime	Supports JavaHelp viewer for Admin Console help. This RPM is not installed by default.
`sun-nss`	Network Security Services (NSS) libraries.	Needed to support C language clients. This RPM is not installed by default.
`sun-nspr`	Netscape Portable Runtime (NSPR) libraries	Needed to support C clients. This RPM is not installed by default.
`sun-saaj`	SOAP with Attachments API for Java: API and runtime	Required to support Java clients using SOAP/JAXM API. This RPM is not installed by default.
`sun-jaxp`	Message Queue Java API for XML Processing (JAXP): API and runtime	Required to support Java clients using SOAP/JAXM API. This RPM is not installed by default.
`sun-javamail`	JavaMail: API and runtime	Required to support Java clients using SOAP/JAXM API. This RPM is not installed by default.
`sun-jaf`	JavaBeans Activation Framework: API and runtime	Required to support Java clients using SOAP/JAXM API. This RPM is not installed by default.

Change to the directory containing the Message Queue distribution files.

cd mq3_7-ent

Log in as root or change to superuser.

For example, type the following at a command prompt:

su root

When prompted, type your root password.

Note –
Remember to migrate data if necessary. See Migrating Files from an Earlier Installation for more information.

If you intend to install all of the Message-Queue-specific RPM packages (packages which start with sun-mq), you will need to run the mqinstall script.

Please note that the install script will overwrite all Message-Queue-specific RPM packages, and will not install any shared RPM packages. You must install shared RPM packages manually, as described in Step 7.
1. Run the mqinstall script.
  
  ./mqinstall
  
  The script lists the distribution RPM packages including their version numbers, if any, that are already installed, and then lists the RPM packages about to be installed.
  
  Note –
  If any of the Message Queue RPM packages listed is already installed and its version is newer, then you will probably not want to install the corresponding Message Queue RPM package. In that case, enter n (no) and continue with Step 7.
  
  The mqinstall script does not install the sun-mq-compat RPM package by default and you should only have it installed if you need it. For example, if your existing client applications contain scripts that depend upon former file locations (such as jar files), you will need to install the sun-mq-compat RPM package. To install this RPM package, see Step 7.
2. Enter y (yes) if you want to install all the Message-Queue-specific RPM packages. Otherwise, enter n (no) and continue with Step 7.
  
  If you run the script, it creates a log file in the following directory:
  
  /var/sadm/install/logs
  
  The /opt/sun/mq directory and its contents are created, and files are placed in other locations as well (see Migration Issues).

If you want to install a subset of the Message QueueRPM packages, if you want to install shared RPM packages, or if you do not want to overwrite later versions of RPM packages, do the following:
1. Change to the rpms directory.
  
  cd rpms
2. Run the rpm install command to install the RPM packages.
  
  rpm -ivh --nodeps rpmPkg1.rpm rpmPkg2.rpm rpmPkg3.rpm

Back up the imq3_7-ent-linx86.zip file from your temporary working directory.

This is your logical media. Treat this file as you would any other installation media. Place a copy in a safe location in case you encounter a situation (such as a system failure) that requires reinstallation of the product.

Clean up all remaining files in your temporary working directory.

Note –
The instance data for any pre-existing broker instance is owned by the user that created that instance. Therefore, once installation is complete, be sure to run any Message Queue broker instance (using the -name instanceName option) as the owner with privileges to the /var/sun/mq/instances/instanceName directory. This applies to the default broker instance (named imqbroker) as well.

Installed Directory Structure

Table 3–3 shows the installed directory structure for a full (all RPMs) installation of Message Queue 3.7 UR1 on the Linux platform. (The directory structure may vary if you perform a partial installation.)

Note –

File locations for Message Queue bundled with Sun Java System Application Server may differ from those shown in the table.

Table 3–3 Installed Directory Structure (Linux)


Directory	Contents
`COPYRIGHT`(not installed)	Copyright text file
`ENTITLEMENT`	Evidence of purchase
`DISTRIBUTIONREADME`	Lists redistributable files
`LICENSE` (not installed)	License text file
`README`(not installed)	README text file
`THIRDPARTYLICENSECREADME`	NSS/NSPR license
`/opt/sun/mq/bin`	Executable files for the following administration tools: Administration Console (`imqadmin`) Broker utility (`imqbrokerd`) Command utility (`imqcmd`) Object Manager utility (`imqobjmgr`) Database Manager utility (`imqdbmgr`) User Manager utility (`imqusermgr`) Key Tool utility (`imqkeytool`)
`/opt/sun/mq/share/lib`	Support files for Message Queue Java client runtime. `.jar` files for building and running Java Message Service (JMS) client applications `.rar` files for JMS Resource Adapter `.war` files for HTTP servlet deployment
`/opt/sun/mq/share/lib/ext`	Files needed for JDBC-based persistence
`/opt/sun/mq/private/share/lib`	Support files for Message Queue tools and processes
`/opt/sun/mq/private/share/lib/props`	Broker's default configuration files
`/opt/sun/mq/private/share/lib/help`	Message Queue help files
`/opt/sun/mq/private/share/lib/images`	Admin GUI image files
`/opt/sun/mq/javadoc`	Message Queue and JMS API documentation in JavaDoc format
`/opt/sun/mq/examples`	Example Java client applications
`/opt/sun/mq/include`	Header files to support C client applications
`/var/opt/sun/mq`	Message Queue working storage
`/var/opt/sun/mq/instances`	Configuration properties, file-based persistent data stores, log files, flat-file user repositories, and access control properties files for individual broker instances
`/etc/opt/sun/mq`	License files, instance template files, and `rc` script configuration files for automatic startup

Configuring the Java Runtime

At startup time, the Message Queue broker checks to make sure it has access to the required Java runtime version (JDK/JRE 1.5). There are a number of ways you can configure or set the JRE used by the broker. These are shown in the following list, in order of precedence:

To Set the JRE Used by the Broker

Pass in the JDK or JRE using either the imqbrokerd -javahome or -jrehome command line options, respectively. (If both are passed in, the last one on the command line will take precedence.)

Set the JDK or JRE in the IMQ_JAVAHOME environment variable.

Let the broker use the installed JDK/JRE. The broker will pick up the latest version JDK/JRE installed on the system (greater than 1.4 ).

To find out which JDK/JRE the broker is using, start the broker with the following command:
imqbrokerd -verbose

Locating RPM Information

You can query the RPM database to determine the installed version of RPMs.

To query the description tag from an installed RPM, use the following command:

rpm -q --queryformat ’%{DESCRIPTION}\\n’ sun-mq

This output shows a Version 3.7 UR1 sun-mq RPM.

SUNW_PRODVERS=3.7.0.1

Uninstalling Message Queue on Linux

The following instructions explain how to uninstall Message Queue on Linux.

To Remove Message Queue on Linux

Stop any running client applications.

Stop any running brokers. (You will be prompted for the admin user name and password.)
imqcmd shutdown bkr [-b hostName:port]

Unless you want to retain dynamic data, the Message Queue flat file user repository, and the Message Queue access control properties file associated with each broker instance, remove this data using the following command.
imqbrokerd -name instanceName -remove instance

Get the uninstall script.

Find the zipped distribution file used to install Message Queue and place it in a temporary directory, temp_directory.

Change directories to temp_directory.
cd temp_directory

Unzip the distribution file.

unzip mq3_7-ent-linx86.zip

Change to the directory containing the Message Queue packages.

cd mq3_7-ent

Become root.
su root
When prompted, type your root password.

Run the uninstall script.
./mquninstall
The installation script lists any installed Message Queue RPM packages that are not shared. (It does not list shared Message Queue RPM packages installed with Message Queue, and which might be in use by other programs.)

If you want to uninstall all the listed RPM packages, enter y (yes) and skip to Step 14. Otherwise, continue with Step 12.

If you do not want to uninstall all of the Message Queue RPM packages, then enter n (no), and use the rpm -e command, as described in Step 13, to uninstall the specific RPM packages you want to remove.

Remove the Message Queue RPM packages manually using the following command:
rpm -e packageName [[packageName]...]
Where packageName specifies a Message Queue RPM package.

Because other products might be using Message Queue RPM packages, be careful about removing them.

Exit the shell.

Where To Go Next

Read the README and Message Queue Release Notes files.

The README includes information on where to find documentation, news and updates, and how to send feedback.
The Message Queue Release Notes contain information on code and documentation changes, open bugs, and important technical notes. This document is available on the Sun Java System documentation Web site.

For an overview of Sun Java System Message Queue concepts, see the Message Queue Technical Overview.

For a brief introduction to writing and compiling a client application, see the Message Queue Developer's Guide for Java Clients or the Message Queue Developer's Guide for C Clients.

For details on configuring brokers and managing a Message Queue messaging system, see the Message Queue Administration Guide.

For class and member information used when writing a client application, browse the API documentation in the IMQ_HOME/javadoc directory.