Previous Contents Next |
Sun Java System Message Queue 3.5 SP1 Installation Guide

> ## Chapter 2
> Solaris Installation

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

> - Hardware and Software Requirements
> - Installing Message Queue on Solaris
> - Configuring Message Queue for Automatic Startup
> - Configuring the Java Runtime for Message Queue
> - Upgrading from Platform to Enterprise Edition
> - Where To Go Next
> - Uninstalling Message Queue on Solaris

> ##

> 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, (SPARC platforms) Solaris 9 (X86 platform) Note: To ensure proper operation of Message Queue, you should install all required Solaris Patches for Java 2. For the latest information about the patches and to download the recommended and required patches, see: http://java.sun.com/j2se/1.4.2/download.html
> CPU | Sun UltraSPARC™ Intel Pentium 2 (or compatible)
> RAM | 256 Mbytes
> Disk space | The compressed installation file is approximately 9 Mbytes. The temporary working directory used for extracting the installation files requires an additional 9 Mbytes. The installed product requires approximately 9 Mbytes of hard drive space. Message Queue, 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 Solaris. The Message Queue software distribution CD includes the required JRE version at the time of release.

> ##

> Installing Message Queue on Solaris

> The Message Queue product can be downloaded from the Sun Java System website or installed from the product CD-ROM. See the appropriate section below for details.

> ### Finding Earlier Message Queue Versions

> Because Message Queue is installed with other products (such as Solaris 9, 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 packageName | grep PRODVERS

> where packageName is any of the Message Queue packages. The package version is the value of SUNW_PRODVERS.

> 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.5 SP1.

> ### Upgrading from Previous Versions

> To upgrade from Message Queue 3.0.x and 3.5 versions, you need not uninstall those versions—they will be over-written. However, if you are upgrading from Message Queue 2.0, it is recommended that you first uninstall Message Queue 2.0 software, as described in the Message Queue 2.0 Installation Guide, before installing Message Queue 3.5 SP1. Also check the Message Queue 3.0.1 Release Notes for information about migrating any existing Message Queue 2.0 data you wish to preserve

> ### 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-2.

> Table 2-2 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 /*.war war files used for HTTP servlet deployment /*.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 /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 (Enterprise Edition only)
> /opt/SUNWimq/ lib/ | Libraries needed to support Message Queue C clients (Enterprise Edition only)1
> /opt/SUNWimq/ demo/C/ | Examples for writing C clients (Enterprise Edition only)

> 1See Table 1-2 for the versions of NSPR and NSS needed to support the C-API.

> ### Installing from the Web

> 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 from the Web

> 1. Read the product license. Installation and use of the product is subject to acceptance of the license agreement.
> 2. 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 edition and hardware platform:

> Table 2-3 Message Queue 3.5 SP1 Solaris Distribution Files

> Edition | SPARC | X86
> --- | --- | ---
> Platform | imq3_5-plt-solsparc.zip | imq3_5-plt-soli386.zip
> Enterprise | imq3_5-ent-solsparc.zip | imq3_5-ent-soli386.zip

> 3. Change directories:

> cd temp_directory

> 4. Unzip the distribution file.

> unzip imq3_5-edition-platform.zip

> where edition is plt or ent, depending on the edition, and platform is solsparc or soli386, depending on the platform.

> The unzip command creates a mq3_5-edition directory which contains the distribution files: LICENSE, README, LICENSEREADME\THIRDPARTYLICENSEREADME, and COPYRIGHT files; install and uninstall scripts; a patches directory; and a pkgs directory that contains the Message Queue packages.

> Table 2-4 describes the Message Queue packages, and Table 2-5 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-4 Packages in Solaris Bundle

> # | Package | Description | Note
> --- | --- | --- | ---
> 1 | SUNWaclg1 | Apache Commons Logging Framework: API and runtime | Required to support Java clients using SOAP/JAXM API.
> 2 | SUNWiqcdv | C header files and demo files | Required for developing C client programs (Enterprise Edition only).
> 3 | SUNWiqcrt | C client shared libraries | Required for running C client programs (Enterprise Edition only).
> 4 | SUNWiqdoc | Message Queue Java client API javadoc and example applications | Needed only for Java client development.
> 5 | 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.
> 6 | SUNWiqjx | Message Queue Java API for XML Messaging (JAXM): API and runtime | Required to support Java clients using SOAP/JAXM API.
> 7 | SUNWiqlpl or SUNWiqlen | Message Queue license files for Platform or Enterprise Edition message server | Depends on Message Queue edition.
> 8 | SUNWiqr | Message Queue message server root package | Needed for Message Queue executables.
> 9 | SUNWiqsup | JNDI and JSSE jar files | Includes the JNDI and JSSE jar files needed for client development and deployment with JDK 1.2 and 1.3.
> 10 | SUNWiqu | Message Queue message server and administration tools |
> 11 | SUNWiquc | Message Queue Java API for JMS messaging and Java client runtime. | Required to support Java clients using JMS API.
> 12 | SUNWiqum | Message Queue JMS/SOAP Message Transformer API and runtime | Required to perform conversions between SOAP messages and JMS messages.
> 13 | SUNWjaf1 | JavaBeans Activation Framework: API and runtime | Required to support Java clients using SOAP/JAXM API.
> 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.
> 15 | SUNWjmail1 | JavaMail: API and runtime | Required to support Java clients using SOAP/JAXM API.
> 16 | SUNWpr1 | Netscape Portable Runtime (NSPR) libraries | Needed to support C clients (Enterprise Edition only).
> 17 | SUNWtls1 | Network Security Services (NSS) libraries. | Needed to support C language clients (Enterprise Edition only).
> 18 | SUNWxsrt1 | SOAP with Attachments API for Java: API and runtime | Required to support Java clients using SOAP/JAXM API.

> 1This package is shared by a number of Sun Java System products.

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

> Table 2-5 Packages Required for Various Scenarios

> Scenario | Packages Needed | Notes
> --- | --- | ---
> Message Queue message server and administration tools | SUNWiqr SUNWiqu SUNWiqlpl or SUNWiqlen 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 (JDK 1.2 and 1.3 only) | Can be installed on a system without a Message Queue message server.
> Developing and/or deploying Java clients using the SOAP/JAXM API | SUNWaclg SUNWjaf SUNWjmail SUNWiqjx SUNWxsrt 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 SUNWtls | Enterprise Edition only.

> 5. Change to the directory containing the Message Queue distribution files.

> cd mq3_5-edition

> 6. Become root:

> su root

> When prompted, type your root password.

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

> showrev -a

> Output indicating incompatible patches looks like this:

> Patch: 114045-05 Obsoletes: Requires: Incompatibles:
> Packages: SUNWpr, SUNWtls

> If patches are shown to packages listed in Table 2-4, you might not want to install those particular Message Queue packages, and you should pay close attention to Step 8a.

> If you mistakenly downgrade your NSS or NSPR packages back to the unpatched versions, you can upgrade to the patched versions by installing the patches that are included in the Message Queue solaris bundle:

> 1. Remove the old patches:

> //use actual patch # shown in showrev -a in place of XX
> #patchrm 114045-XX (Solaris 8 sparc)
> //or
> #patchrm 114049-XX (Solaris 9 sparc)
> //or
> #patchrm 114046-XX (Solaris 8 i386)
> //or
> #patchrm 114050-XX (Solaris 9 i386)

> 2. Install the patches back.

> #cd mq3_5-<edition>/patches
> #patchadd 114045-XX (Solaris 8 sparc)
> //or
> #patchadd 114049-XX (Solaris 9 sparc)
> //or
> #patchadd 114046-XX (Solaris 8 i386)
> //or
> #patchadd 114050-XX (Solaris 9 i386)

> 8. If you intend to install all the packages listed in Table 2-4, you will need to run the mqinstall script. Please note that this script will overwrite all the listed packages.
> 1. Run the mqinstall script.

> ./mqinstall

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

> Note | If any of the patches found in Step 7 are packages that are already installed, then you will probably not want to install the corresponding Message Queue packages. In that case, enter n (no) and continue with Step 9.

> Note | The mqinstall utility does not install package #9 (SUNWiqsup) in Table 2-4. If you are doing client development using JDK 1.2 or 1.3, you will need to install the SUNWiqsup package as described in Step 9.

> 2. Enter y (yes) if you want to install all the packages, and skip to Step 10. Otherwise, enter n (no) and continue with Step 9.

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

> /var/sadm/install/logs/

> 9. If you do not want to install all of the packages listed in Table 2-4 (you want only a subset, or you don’t want to over-write later versions of packages), do the following:
> 1. Change to the pkgs directory

> cd pkgs

> 2. 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-4). 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, perhaps asking for additional information, and eventually returns to the original prompt, displaying the list of packages available for installation.

> 3. Type q to quit.
> 10. Exit the root shell.
> 11. 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.

> 12. Clean up all remaining files in your temporary working directory. For your convenience, you should save the uninstall script.

> Note | The instance data for any pre-existing broker instance (including the default broker instance, named imqbroker) is owned by whoever 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.

> ### Installing from CD-ROM

> The following instructions explain how to install the Message Queue product on Solaris from CD-ROM.

> ##### To Install Message Queue on Solaris from CD-ROM

> 1. Log in as root or change to superuser.

> For example, type the following at a command prompt:

> su root

> Then type your superuser password.

> 2. Insert the Message Queue CD into your CD-ROM drive.

> If the Volume Manager™ software is running on your machine, the CD-ROM is automatically mounted to the /cdrom/messagequeue3_5 directory.

> If the Volume Manager is not running on your machine:

> - Create a directory called /cdrom/messagequeue3_5 by typing:

> mkdir -p /cdrom/messagequeue3_5

> - Mount the CD-ROM manually:

> mount -rF hsfs cdrom-device /cdrom/messagequeue3_5

> An example of cdrom-device is /dev/dsk/c0t0d0s0.

> Note | Volume Manager is a tool provided on Solaris that allows you to perform administrative tasks, such as mounting CD-ROMs, more easily. Volume Manager mounts a CD-ROM as /cdrom/name_of_media, where name_of_media is determined from the CD-ROM itself.

> Open and read (using your preferred text editor) the LICENSE file located in the solaris-sparc/ or solaris-x86/ directory of the CD.

> - If you choose NOT to accept the license agreement, discontinue installation and contact the place where you purchased the product to determine the return policy.
> - If you choose to accept the agreement, continue with the installation steps below.
> 3. Change to the directory on the CD containing the installation packages. For example, type:

> cd /cdrom/messagequeue3_5/solaris-sparc

> or

> cd /cdrom/messagequeue3_5/solaris-x86

> The contents of this directory vary depending on the product edition.

> 4. Continue with Step 6 under Installing from the Web.

> ### 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 Startup

> If you wish 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-6:

> Table 2-6 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

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

> env DEBUG=1 /etc/rc3.d/S52imq start

> ##

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

> 1. 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).
> 2. Set the JDK or JRE in the IMQ_JAVAHOME environment variable.
> 3. Let the broker use the installed JDK.

> This is the JDK located in /usr/j2se

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

> imqbrokerd -verbose

> ##

> Upgrading from Platform to Enterprise Edition

> Message Queue comes in two editions, as explained in Product Editions. Upgrading from the Platform to Enterprise Edition must be done at the same version level; that is, you can upgrade from Platform Edition 3.5 SP1 to Enterprise Edition 3.5 SP1, but you cannot upgrade from Platform Edition 3.0.1 to Enterprise Edition 3.5 SP1

> To upgrade from the Platform Edition to the Enterprise Edition, you need to first purchase the Enterprise Edition, and then install, as described below, the Enterprise Edition license contained in the distribution, plus the C-API packages, if you wish to write C client programs. Installation of these packages does not overwrite the Message Queue 3.5 SP1 modules already installed and does not modify the configuration of your Message Queue messaging system.

> To upgrade to the Enterprise Edition, you need only the following packages:

> Table 2-7 Upgrade Packages in Solaris Enterprise Bundle

> # | Package | Description | Note
> --- | --- | --- | ---
> 7 | SUNWiqlen | Message Queue license file for Enterprise Edition message server |
> 3 | SUNWiqcrt | C-API shared libraries | Required for running C client programs (Enterprise Edition only)
> 2 | SUNWiqcdv | C-API header files and demo files | Required for developing C client programs (Enterprise Edition only)
> 16 | SUNWpr1 | Netscape Portable Runtime (NSPR) libraries. | Needed to support C client programs (Enterprise Edition only)
> 17 | SUNWtls1 | Network Security Services (NSS) libraries. | Needed to support C client programs (Enterprise Edition only)

> 1This is a shared package.

> ##### To Upgrade to Enterprise Edition on Solaris

> 1. Stop any running brokers. (You will be prompted for user name (admin user) and password.)

> imqcmd shutdown bkr [-b hostName:port]

> 2. Follow the installation procedure in Installing from the Web, Step 1 through Step 6 or in Installing from CD-ROM, Step 1 through Step 3.
> 3. Add the Enterprise Edition packages:
> 1. Change to the pkgs directory

> cd pkgs

> 2. Run the pkgadd command to install the packages in Table 2-7 that you want; you might want only a subset, or you might not want to over-write later versions of packages. For example:

> pkgadd -d . SUNWiqlen

> 3. Type q to quit.
> 4. Verify that the Enterprise Edition license is available by running the following command:

> imqbrokerd -license

> ##

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

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

> 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 Solaris

> The following instructions explain how to uninstall Message Queue.

> ##### To Remove Message Queue on Solaris

> 1. Stop any running client applications.
> 2. Stop any running brokers. (You will be prompted for user name (admin user) and password.)

> imqcmd shutdown bkr [-b hostName:port]

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

> 4. Get the uninstall script from the distribution CD or follow Step 5 through Step 7. If you already have the uninstall script you can proceed to Step 9.
> 5. Find the zipped distribution file used to install Message Queue (see Step 11) and place it in a temporary directory, temp_directory.
> 6. Change directories to temp_directory:

> cd temp_directory

> 7. Unzip the distribution file.

> unzip imq3_5-edition-platform.zip

> where edition is plt or ent, depending on the edition, and platform is solsparc or soli386, depending on the platform.

> 8. Change to the directory containing the Message Queue packages.

> cd mq3_5-edition

> 9. Become root:

> su root

> When prompted, type your root password.

> 10. Run the un-install 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.)

> 11. If you want to un-install all the listed packages, enter y (yes), and skip to Step 16. Otherwise, continue with Step 12.
> 12. If you do not want to un-install all of the Message Queue packages, then enter n (no), and use the pkgrm command, as described in Step 13, to un-install the specific packages you want to remove.
> 13. 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.

> 14. When prompted, confirm your removal request by typing y.
> 15. Type q to quit.
> 16. Exit the root shell.

> Previous Contents Next

> Copyright 2004 Sun Microsystems, Inc. All rights reserved.