Sun Java logo     Previous      Contents      Next     

Sun logo
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

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.

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

    4. cd temp_directory

  4. Unzip the distribution file.

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

    6. cd mq3_5-edition

  6. Become root:

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

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

      		2.

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

      		3.

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

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

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

      2. cd pkgs

    2. run the pkgadd command to install the packages you want:

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

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

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

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

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

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

    4. 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.)

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

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

      3. pkgadd -d . SUNWiqlen

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

    5. imqbrokerd -license

Where To Go Next

Read the README and Message Queue Release Notes files.

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

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

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

    7. cd temp_directory

  7. Unzip the distribution file.

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

    9. cd mq3_5-edition

  9. Become root:

    10. su root

    When prompted, type your root password.

  10. Run the un-install script.

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

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