Sun Java System Message Queue 3 2005Q4 Installation Guide |
Chapter 2
Solaris InstallationThis 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 RequirementsAt a minimum, your Solaris system (SPARC or x86) should satisfy the requirements indicated in the following table.
Installing Message Queue on SolarisThe 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:
pkginfo | grep SUNWiq
If Message Queue packages are already installed, you can check the version by entering:
pkgparam -v SUNWiqu SUNW_PRODVERS
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:
pkginfo | grep SUNWiqlen
If the following output appears, you have Enterprise Edition installed on your system:
application SUNWiqlen Sun Java(tm) System Message Queue Enterprise Edition Broker
If the SUNWiqlen package is not listed, you have Platform Edition installed.
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
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:
/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
SUNWjaxp1
Java API for XML processing
Required to support Java clients using SOAP/JAXM API.
This package is not installed by default.
14
SUNWjhrt1
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
SUNWjmail1
JavaMail: API and runtime
Required to support Java clients using SOAP/JAXM API.
This package is not installed by default.
19
SUNWpr1
Netscape Portable Runtime (NSPR) libraries
Needed to support C clients.
This package is not installed by default.
20
SUNWprx1
Netscape Portable Runtime (NSPR) libraries
Needed to support C clients.
(64-bit) (SPARC only)This package is not installed by default.
21
SUNWtls1
Network Security Services (NSS) libraries.
Needed to support C clients.
This package is not installed by default.
22
SUNWtlsx1
Network Security Services (NSS) libraries.
Needed to support C clients.
(64-bit SPARC only)This package is not installed by default.
23
SUNWtlsu1
Network Security Services Utilities Programs
Needed to support SSL for C clients.
This package is not installed by default.
24
SUNWtlsux1
Network Security Services Utilities Programs
Needed to support SSL for C clients.
(64-bit SPARC only)This package is not installed by default.
25
SUNWxsrt1
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:
- 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.
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:
imqbrokerd -version
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 StartupIf 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:
/etc/imq/imqbrokerd.conf
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:
env DEBUG=1 /etc/init.d/imq start
Configuring the Java Runtime for Message QueueAt 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:
To figure out why a broker is picking up a specific JDK/JRE, you can start the broker with the following command:
imqbrokerd -verbose
Where To Go NextRead the README and Message Queue Release Notes files.
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.
To uninstall the product, see the following section.
Uninstalling Message Queue on SolarisThe following instructions explain how to uninstall Message Queue.
To Remove Message Queue on Solaris
- Stop any running client applications.
- Stop any running brokers. You will be prompted for user name (admin user) and password.
imqcmd shutdown bkr [-b hostName:port]
- 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
- Find the zipped distribution file used to install Message Queue (see Step 12) and place it in a temporary directory, temp_directory.
- Change directories to temp_directory:
cd temp_directory
- Unzip the distribution file.
unzip mq3_6-plt-platform.zip
where platform is solsparc or soli386, depending on the platform.
- Change to the directory containing the Message Queue packages.
cd mq3_6-plt
- Become root:
su root
When prompted, type your root password.
- Run the uninstall script.
./mquninstall
The installation script lists Message Queue packages that are not shared, if any, that are currently installed. (It does not list shared Message Queue packages installed with Message Queue, and which might be in use by other programs.)
- If you want to uninstall all the listed packages, enter y (yes), and skip to Step 15. Otherwise, continue with Step 11.
- If you do not want to uninstall all of the Message Queue packages, then enter n (no), and use the pkgrm command, as described in Step 12, to uninstall the specific packages you want to remove.
- Remove the Message Queue packages, using the following command:
pkgrm packageName
where packageName is any of the Message Queue packages. To remove multiple packages, separate the package names by a space.
Because other products might be using Message Queue packages, be careful about removing them. The pkgrm command will warn you of any dependencies on a package before removing it.
- When prompted, confirm your removal request by typing y.
- Type q to quit.
- Exit the root shell.