Chapter 3 Linux Installation

This chapter explains the following topics as they apply to a Linux installation:

Hardware and Software Requirements

At a minimum, your Linux system should satisfy the minimum requirements indicated in the following table.

Table 3-1 Hardware and Software Requirements for Linux
Component	Requirements
Operating system	Red Hat Advanced Server 2.1 Update 2
CPU	Intel Pentium 2 (or compatible)
RAM	256 Mbytes
Disk space	The zip file containing the product is approximately 9 Mbytes. The installed product requires approximately 8 Mbytes of hard drive space. MQ, however, may need more space if the broker stores persistent messages locally.
Java 2 Standard Edition (J2SE)	See Table 1-1 for the supported versions of the Java Runtime Environment (JRE) and Java Software Development Kit (JDK) that are supported on Linux. The MQ software distribution CD includes the required JRE version at the time of release.

Installing MQ on Linux

The Sun ONE Message Queue product can be downloaded from the Sun ONE website or installed from the product CD-ROM. See the appropriate section below for instructions.

Finding and Removing Earlier MQ Versions

Because MQ is installed with other products (such as Solaris 9, Sun ONE Application Server, and possibly others), you should check whether MQ has already been installed on your system, and uninstall it before installing MQ 3.5.


Note	If you are upgrading from MQ 3.0 versions, you are required to first uninstall MQ 3.0 version software, as described in the following section.

If you find that an earlier version of MQ is already on your system, you need to decide if you want to preserve any security-related data (flat-file user repository, access control file, or passfile). If, so, you will need to use the mqmigrate utility, as explained in subsequent paragraphs, before uninstalling the earlier version of MQ. If you do not want to preserve your old data files, you do not have to run the mqmigrate utility.

Note that RPM’s are now relocatable for all files in the /opt directory. You can use --prefix=dir with the -i option if you want to change the default /opt location.

Depending on the version, MQ might have been installed using tar files or the Red Hat Package Manager (RPM). To check for installed versions, therefore, you need to check for both. It is recommended that you check first for RPM installations and then for tar file installations.

Migrating Files from Non-Standard Locations

The mqmigrate utility has a new option that allows you to migrate data that has been installed in a non-standard location. The syntax for the new option is as follows:

Where baseDirectory specifies the non-standard directory where the files were installed. For example, if the old data was untar’ed in the /export directory, you should migrate the old data using the command

Finding and Removing MQ RPM’s (Version 3.0.1 SP1 or Later Only)

To Find and Remove Earlier RPM-Installed Versions of MQ

Enter the following command:

rpm -qa | grep imq

If found, the version numbers of any RPM’s are imbedded in the RPM name. If none are found, proceed to "Finding and Removing an MQ Tar-Based Installation."

If you find MQ RPM’s of a version earlier than 3.5, remove them as follows:

Run the mqmigrate utility (in the MQ 3.5 distribution) after completing Step 5):

./mqmigrate

The mqmigrate utility moves existing broker instance data (broker configuration files and persistent data) and security-related files, to new MQ 3.5 locations.

Remove the existing MQ installed software.

rpm -e RPMName

Finding and Removing an MQ Tar-Based Installation

To Find and Remove Earlier Tar-Based Installed MQ

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

If found, proceed to Step 2.

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

If there is no previous MQ installation, proceed to install MQ by following the directions in "Installing from the Web" or "Installing from CD-ROM".

If you find an earlier MQ installation in the default location (/opt/imq/bin), remove it as follows:

Run the mqmigrate utility (in the MQ 3.5 distribution) after completing Step 5):

./mqmigrate

The mqmigrate utility moves existing broker instance data (broker configuration files and persistent data) and security-related files, to new MQ 3.5 locations.

Remove the /opt/imq/ directory and all its contents.

rm -rf /opt/imq

Installed Directory Structure

The install image below reflects a full (all RPM’s) Linux installation. This image might vary if you perform a partial installation.


Note	File locations for MQ bundled with Sun ONE Application Server, may differ from locations specified in Table 3-2.

Table 3-2 Installed Directory Structure: Linux
Linux	Contents
COPYRIGHT (not installed)	Copyright text file
LICENSE (not installed)	License text file
LICENSEREADME/THIRDPARTY- LICENSEREADME (not installed)	License for third party software distributed by MQ: DOM4J, Apache Commons Logging
README (not installed)	README text file
/opt/imq/bin/	Contains the executables for the broker (imqbrokerd) and the following MQ administration tools: Administration Console (imqadmin) Command (imqcmd) Object Manager (imqobjmgr) User Manager (imqusermgr) Database Manager (imqdbmgr) Key Tool (imqkeytool)
/opt/imq/lib/	Contains files that support the MQ Java client runtime: /.jar jar files used to build and run Java JMS client applications /.war war files used for HTTP servlet deployment /*.rar rar files used for MQ resource adapter
/opt/imq/lib/	Contains files used to support MQ tools and processes: /ext location for placing files needed for plug-in persistence capability /props subdirectory contains the broker’s default configuration files /help subdirectory contains MQ help files /images
/etc/opt/imq/	Contains license files, instance template files, and rc script configuration files that can be used for automatic startup
/var/opt/imq/	Working storage directory for MQ. /instances subdirectory which will contain configuration files, log files, access control files, flat-file user repository, and file-based persistent data stores for each broker instance
/opt/imq/ javadoc/	Contains the MQ and JMS API documentation distributed as Javadoc (HTML)
/opt/imq/demo/	Source code for and instructions on how to run Java client example applications:
/opt/imq/ include/	Header files needed to support MQ C clients (Enterprise Edition only)
/opt/imq/lib/	Libraries needed to support MQ C clients (Enterprise Edition only)2
/opt/imq/demo/C/	Examples for writing C clients (Enterprise Edition only)
	The JRE 1.4 files (on Windows only)

Installing from the Web

The following instructions explain how to download and install the MQ product on Linux from the Sun ONE website.

To Install MQ on Linux from the Web

Accept the license agreement on the MQ product download site.

Download the MQ product distribution file from the website into an empty, temporary download directory, temp_directory.

The download file is: imq3_5-edition-linx86.zip

where edition takes one of the following values: plt or ent, depending on whether you are installing the Platform Edition or Enterprise Edition, respectively.

Change to the temp_directory and uncompress the distribution file.

unzip imq3_5-edition-linx86.zip

The unzip command creates a imq3_5-edition directory which contains the distribution files: LICENSE, README, THIRDPARTYLICENSEREADME, and COPYRIGHT files; mqmigrate utility; and an rpms directory that contains the following RPM’s:

imq-3_5-releaseVersion.i386.rpm
(included in both Platform and Enterprise Editions)

imq-ent-3_5-releaseVersion.i386.rpm
(included in Enterprise Edition only)

Change to the directory containing the MQ distribution files.

cd mq3_5-edition

For example, type the following at a command prompt:

su root

When prompted, type your root password.

Install the appropriate RPM’s. Note that the Enterprise Edition requires Platform Edition to be installed.

rpm -ivh rpms/imq-3_5-releaseVersion.i386.rpm
(Platform Edition)

rpm -ivh rpms/imq-ent-3_5-releaseVersion.i386.rpm
(Enterprise Edition )

The /opt/imq directory and its contents are created, and files are placed in other locations as well (see "Upgrade Issues from MQ 3.0.x Versions").

Back up the imq3_5-edition-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 whoever created that instance. Therefore, once installation is complete, be sure to run any MQ broker instance (using the -name instanceName option) as the owner with privileges to the /var/imq/instances/instanceName directory. This applies to the default broker instance (named imqbroker), as well.

Installing from CD-ROM

The following instructions explain how to install the MQ product on Linux from CD-ROM.

To Install MQ on Linux from CD-ROM

Configuring the Java Runtime for MQ

At startup time, a broker (the MQ message server) checks to make sure it has access to the required Java runtime version (JDK/JRE 1.4). 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 find out why a broker is picking up a specific JDK/JRE, you can start the broker with the following command:

Upgrading from Platform to Enterprise Edition

To upgrade from the Platform Edition to the Enterprise Edition, you need to first purchase the Enterprise Edition, and then install, as described below, only the Enterprise Edition license contained in the distribution. Installation of the license does not overwrite the MQ 3.5 modules already installed and does not modify the configuration of your MQ messaging system.

To Upgrade to Enterprise Edition on Linux

Where To Go Next

For an overview of Sun ONE Message Queue concepts, a brief introduction to writing and compiling a client application, see the MQ Java Client Developer’s Guide.

For details on configuring brokers and managing an MQ messaging system, see the MQ Administrator’s Guide.

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

Uninstalling MQ on Linux

To Remove MQ on Linux

Stop any running client applications.

Stop any running brokers.

imqcmd shutdown bkr -u name -p password [-b hostName:port]

Unless you want to retain dynamic data, the MQ flat file user repository, and the MQ access control file associated with each broker instance, remove this data using the following command.

imqbrokerd -name instanceName -remove instance

Become root:

su root

Remove the MQ product.

Issue the following command(s) in the following order:


rpm -e imq-ent	(for Enterprise Editions
rpm -e imq	(for Platform edition only)