Chapter 2 Solaris Installation

This chapter explains the following topics as they apply to a Solaris installation of Message Queue 3 2005Q4 (3.6 SP3), Platform Edition:

Hardware and Software Requirements

At a minimum, your Solaris™ system (SPARC™ or x86) should satisfy the requirements indicated in the following table.

Table 2-1 Hardware and Software Requirements for Solaris
Component	Requirements
Operating system	Solaris 8, Solaris 9, Solaris 10 (SPARC platforms) Solaris 9, Solaris 10 (x86 platform) Note: To ensure proper operation of Message Queue, you should install all required Solaris Patches for Java 2 Platform, Standard Edition 5.0. For the latest information about the patches and to download the recommended and required patches, see: http://java.sun.com/j2se/1.5.0/download.jsp
CPU	Sun UltraSPARC™ Intel Pentium 2 (or compatible)
RAM	256 Mbytes
Disk space	The compressed installation file is approximately 33 Mbytes on the SPARC platform and 22 Mbytes on the x86 platform. The temporary working directory used for extracting the installation files requires an additional 33 Mbytes on the SPARC platform and 22 Mbytes on the x86 platform. The installed product requires approximately 33 Mbytes of hard drive space on the SPARC platform and 22 Mbytes on the x86 platform. Message Queue, however, may need more space if the broker stores persistent messages locally.
Java 2 Platform, Standard Edition (J2SE)	See the Message Queue Release Notes for the supported versions of the Java Runtime Environment (JRE) and Java Software Development Kit (JDK) that are supported on Solaris. The Message Queue software distribution includes the required JRE version at the time of release.

Installing Message Queue on Solaris

The Sun Java System Message Queue product can be downloaded from the Sun Java System website. For hardware and software requirements for component products that can be used with Message Queue, see the Message Queue Release Notes.

Finding Earlier Message Queue Versions

Because Message Queue is installed with other products (such as Solaris 9, Solaris 10, Sun Java System Application Server, and possibly others), you should check whether Message Queue has already been installed on your system. To do so, enter the following command:

If Message Queue packages are already installed, you can check the version by entering:

The product version is the value of SUNW_PRODVERS. Table 2-2 shows the SUNW_PRODVERS value returned for each release.

To check the Message Queue edition installed on your system, enter the following command:

If the following output appears, you have Enterprise Edition installed on your system:

application SUNWiqlen Sun Java(tm) System Message Queue Enterprise Edition Broker

Table 2-2 Value of SUNW_PRODVERS Returned for Message Queue
Message Queue Release	SUNW_PRODVERS Value of the SUNWiqu Package
3.0.1	3.0.1
3.0.1 SP1	3.0.1 SP1
3.0.1 SP 2	3.0.1 SP2
3.5	3.5
3.5 SP1	3.5 SP1
3.5 SP2	3.5 SP2
3 2005Q1 (3.6)	3.6.0.0
3 2005Q1 (3.6 SP1)	3.6.0.1
3 2005Q4 (3.6 SP2)	3.6.0.2
3 2005Q4 (3.6 SP3)	3.6.0.3

If you find that a previous installation already exists on your system, see Upgrading from Previous Versions for information on upgrading to Message Queue 3 2005Q4.

Upgrading from Previous Versions

To upgrade from Message Queue 3.0.x, 3.5, and 3.6 Platform Edition versions, you need not uninstall those versions—they will be over-written.

Installed Directory Structure

The install image below reflects a full (all packages) Solaris installation. This image might vary if you perform a partial installation.


Note	If you want to upgrade to Message Queue 3 2005Q4 (3.6 SP3), Enterprise Edition, you must purchase Message Queue 3 2005Q4, Enterprise Edition and use the Sun Java^TM Enterprise System installer to upgrade your version of Message Queue. Refer to the Sun Java Enterprise System Installation Guide for more information.


Note	File locations for Message Queue bundled with Sun Java System Application Server may differ from locations specified in Table 2-3.

Table 2-3 Installed Directory Structure: Solaris
Solaris	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 Message Queue: DOM4J, Apache Commons Logging
README (not installed)	README text file
/usr/bin/	Contains the executables for the broker (imqbrokerd) and the following Message Queue administration tools: Administration Console (imqadmin) Command (imqcmd) Object Manager (imqobjmgr) User Manager (imqusermgr) Database Manager (imqdbmgr) Key Tool (imqkeytool)
/usr/share/lib/	Contains files that support the Message Queue Java client runtime: /.jar jar files used to build and run Java JMS client applications /.rar rar files used for Message Queue resource adapter
/usr/share/lib/imq/	Contains files used to support Message Queue tools and processes: /ext location for placing files needed for plug-in persistence capability /.war war files used for HTTP servlet deployment /.jar jar files used by the Message Queue system /props subdirectory contains the broker’s default configuration files /help subdirectory contains Message Queue help files /images
/etc/imq/	Contains license files, instance template files, and rc script configuration files that can be used for automatic startup
/var/imq/	Working storage directory for Message Queue. /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
/usr/share/ javadoc/imq/	Contains the Message Queue and JMS API documentation distributed as Javadoc (HTML)
/usr/demo/imq/	Source code for and instructions on how to run Java client example applications:
/opt/SUNWimq/ include/	Header files needed to support Message Queue C clients (when using the Enterprise Edition try license)
/opt/SUNWimq/ lib/	Libraries needed to support Message Queue C clients (when using the Enterprise Edition try license)1
/opt/SUNWimq/ demo/C/	Examples for writing C clients (when using the Enterprise Edition try license)

1See the Message Queue Release Notes for the versions of NSPR and NSS needed to support the C-API.

Installing Message Queue

The following instructions explain how to download and install the Message Queue product on Solaris from the Sun Java System website.

To Install Message Queue on Solaris

Read the product license. Installation and use of the product is subject to acceptance of the license agreement.

Download the Message Queue product distribution file from the website into an empty, temporary working directory, temp_directory.

The zipped distribution file name depends on the Message Queue hardware platform:

Table 2-4 Message Queue 3 2005Q4 Solaris Distribution Files
Edition	SPARC	X86
Platform	mq3_6-plt-solsparc.zip	mq3_6-plt-soli386.zip

Change directories:

cd temp_directory

Unzip the distribution file.

unzip mq3_6-plt-platform.zip

where platform is solsparc or soli386, depending on the platform.

The unzip command creates a mq3_6-plt directory which contains the distribution files: LICENSE, README, LICENSEREADME/THIRDPARTYLICENSEREADME, and COPYRIGHT files; install and uninstall scripts; and a pkgs directory that contains the Message Queue packages, as well as shared Solaris packages that have been updated for use with Solaris 8 (SunOS5.8) and Solaris 9 (SunOS5.9).

Table 2-5 describes the Message Queue packages, and Table 2-6 provides a guide to the packages you need for different use scenarios. In addition, if any of these files already exist on your system, you need to check whether the patch revision number is greater than that provided by Message Queue. If it is, you should do a custom install.

Table 2-5 Packages in Solaris Bundle
#	Package	Description	Note
1	SUNWiqcdv	C header files and demo files	Required for developing C client programs.
2	SUNWiqcrt	C client shared libraries	Required for running C client programs.
3	SUNWiqdoc	Message Queue Java client API javadoc and example applications	Needed only for Java client development.
4	SUNWiqfs	Message Queue JNDI File System Service Provider	Required only for client development and administration tools that use the JNDI FIle System Service Provider. The JNDI Service Provider is not supported for deployment.
5	SUNWiqjx	Message Queue Java API for XML Messaging (JAXM): API and runtime	Required to support Java clients using SOAP/JAXM API.
6	SUNWiqlpl	Message Queue license file for Platform Edition message server	Depends on Message Queue edition.
7	SUNWiqr	Message Queue message server root package	Needed for Message Queue executables.
8	SUNWiqsup	JNDI and JSSE jar files	Includes the JNDI and JSSE jar files needed for client development and deployment with JDK 1.3. This package is not installed by default.
9	SUNWiqu	Message Queue message server and administration tools
10	SUNWiquc	Message Queue Java API for JMS messaging and Java client runtime.	Required to support Java clients using JMS API.
11	SUNWiqum	Message Queue JMS/SOAP Message Transformer: API and runtime	Required to perform conversions between SOAP messages and JMS messages.
12	SUNWjaf1	JavaBeans Activation Framework: API and runtime	Required to support Java clients using SOAP/JAXM API. This package is not installed by default.
13	SUNWjaxp¹	Java API for XML processing	Required to support Java clients using SOAP/JAXM API. This package is not installed by default.
14	SUNWjhrt¹	JavaHelp: API and runtime	Required if installing on Solaris 8. (Solaris 9 and above already have this package installed.) Will only install if a JVM 1.4 or greater has first been installed. This package is not installed by default.
15	SUNWjhdev	JavaHelp Development Utilities	Required to upgrade the current JavaHelp runtime package (SUNWjhrt) This package is not installed by default.
16	SUNWjhdoc	JavaHelp Documentation	Required to upgrade the current JavaHelp runtime package (SUNWjhrt) This package is not installed by default.
17	SUNWjhdem	JavaHelp Demos	Required to upgrade the current JavaHelp runtime package (SUNWjhrt) This package is not installed by default.
18	SUNWjmail¹	JavaMail: API and runtime	Required to support Java clients using SOAP/JAXM API. This package is not installed by default.
19	SUNWpr¹	Netscape Portable Runtime (NSPR) libraries	Needed to support C clients. This package is not installed by default.
20	SUNWprx¹	Netscape Portable Runtime (NSPR) libraries	Needed to support C clients. (64-bit) (SPARC only) This package is not installed by default.
21	SUNWtls¹	Network Security Services (NSS) libraries.	Needed to support C clients. This package is not installed by default.
22	SUNWtlsx¹	Network Security Services (NSS) libraries.	Needed to support C clients. (64-bit SPARC only) This package is not installed by default.
23	SUNWtlsu¹	Network Security Services Utilities Programs	Needed to support SSL for C clients. This package is not installed by default.
24	SUNWtlsux¹	Network Security Services Utilities Programs	Needed to support SSL for C clients. (64-bit SPARC only) This package is not installed by default.
25	SUNWxsrt¹	SOAP with Attachments API for Java: API and runtime	Required to support Java clients using SOAP/JAXM API. This package is not installed by default.

1This 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.

Table 2-6 provides a guide to the packages you need for different use scenarios:

Table 2-6 Packages Required for Various Scenarios
Scenario	Packages Needed	Notes
Message Queue message server and administration tools	SUNWiqr SUNWiqu SUNWiqlpl SUNWiquc SUNWjhrt SUNWiqfs (optional)	Required for a Message Queue message server to run on a host.
Developing and/or deploying Java clients using the JMS API	SUNWiquc SUNWiqdoc (optional) SUNWiqsup	Can be installed on a system without a Message Queue message server. Note: The SUNWiqsup package is provided for development and deployment of clients using JDK 1.3. This package is not installed by default.
Developing and/or deploying Java clients using the SOAP/JAXM API	SUNWjaf SUNWjmail SUNWiqjx SUNWxsrt SUNWjaxp SUNWiqdoc (optional)	Can be installed on a system without a Message Queue message server. Note: SOAP clients require JDK1.4.
Developing and/or deploying Java clients using the JMS/SOAP Message Transformer	SUNWiqum Plus all packages needed to support Java clients using both the JMS and SOAP/JAXM API	Can be installed on a system without a Message Queue message server. The Message Queue Message Transformer API depends on both the JMS and SOAP APIs.
Developing and/or deploying C clients	SUNWiqcrt SUNWiqcdv SUNWpr SUNWprx SUNWtls SUNWtlsx SUNWtlsu SUNWtlsux (for SSL)	The SUNWprx, SUNWtlsx, and SUNWtlsux packages are 64-bit packages for use with the Solaris SPARC platform. Solaris x86 does not support 64-bit packages. The SUNWtlsu and SUNWtlsux packages are used to create and manage NSS certificate database files by a C client when using SSL.

Change to the directory containing the Message Queue distribution files.

cd mq3_6-plt

Become root:

su root

When prompted, type your root password.

Run the mqinstall script. This script will overwrite all of the Message-Queue-specific packages listed in Table 2-5.

./mqinstall

The script lists the distribution packages, if any, that are already installed, and then lists the packages about to be installed.

Please note that the install script will not install any shared packages (packages which do not begin with SUNWiq and which might already be installed on your system). You must install shared packages manually, as described in Step 9.

Enter y (yes) if you want to install all the packages. If you want to install the packages manually, enter n (no).

If you run the mqinstall script, it creates a log file in the following directory:

/var/sadm/install/logs/

Check your system for patches to any of the non-Message-Queue-specific packages listed in Table 2-5 (packages which do not begin with SUNWiq and which might already be installed on your system). Enter the following command to check for patches:

% pkgparam -v <pkgname> PATCHLIST

For example, to check which patches have been applied to SUNWpr (NSPR), use the following command:

% pkgparam -v SUNWpr PATCHLIST

The output showing the patch list may look like this:

PATCHLIST='114049-11 117724-05'

If patches are shown to packages listed in Table 2-5, you might not want to install those particular Message Queue packages.

If you want to install a subset of the packages listed in Table 2-5, you want to install shared packages, or you do not want to over-write later versions of packages, do the following:

Change to the pkgs directory

cd pkgs

run the pkgadd command to install the packages you want:

pkgadd -d ./ -a admin.conf

The pkgadd utility lists the names of all packages in the directory available for installation (see Table 2-5). When prompted, indicate the packages you want to install. (The -a admin.conf option permits an over-write of any packages that are already installed on your system.)

The pkgadd utility installs the packages you specified, possibly asking for additional information, and eventually returns to the original prompt, displaying the list of packages available for installation.

Type q to quit.

Exit the root shell.

Back up the zip distribution file from your temporary working directory.

This is your logical media. It will be needed to uninstall or reinstall Message Queue. Treat this file as you would any other installation media and place a copy in a safe location.



Note	The instance data for any pre-existing broker instance (including the default broker instance, named imqbroker) is owned by the user that created that instance. Therefore, once installation is complete, be sure to run any Message Queue broker instance as the owner with privileges to the /var/imq/instances/instanceName directory. You become the owner by logging in as that user.

Checking Your Installation

To check that the expected version of Message Queue is running on your system, navigate to the Message Queue directory and enter the command:

The output to this command specifies the version of the JDK and Message Queue that are installed on your system.

Configuring Message Queue for Automatic Startup

If you want to set the broker (the Message Queue message server) for automatic startup, you need to become root and edit the following configuration file:

The startup properties you can set in this configuration file are shown in Table 2-7:

To check that startup changes are correct (without booting the system), you can, as root, explicitly run the Message Queue initialization script in “debug” mode:

Table 2-7 Broker Startup Configuration Properties
Property Name	Description
AUTOSTART	Specifies (YES/NO) if the broker is automatically started at boot time. Default: NO
ARGS	Specifies command line options and arguments to pass to the broker startup command. See the Message Queue Administration Guide for a listing and description of imqbrokerd command line options. (For example -name instanceName)
RESTART	Specifies (YES/NO) if the broker is automatically re-started if it abnormally exits. Default: YES

Configuring the Java Runtime for Message Queue

At startup time, a broker (the Message Queue message server) 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:

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.

The broker tries to locate the JDK in the following order.

On Solaris 8 or 9:

/usr/jdk/entsys-j2se

/usr/jdk/jdk1.5.*

/usr/jdk/j2sdk1.5.*

/usr/j2se

On Solaris 10:

/usr/jdk/entsys-j2se

/usr/java

/usr/j2se

To figure out why a broker is picking up a specific JDK/JRE, you can start the broker with the following command:

Where To Go Next

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 website.

For an overview of 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 /usr/share/javadoc/imq directory.