Sun logo      Previous      Contents      Next     

Sun ONE Message Queue 3.5 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 MQ, 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. 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 Solaris.

The MQ software distribution CD includes the required JRE version at the time of release.

Installing MQ on Solaris

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

Note

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

Note

Because MQ is installed with other products (such as Solaris 9, Sun ONE Application Server, and possibly others), you might wish to check whether MQ has already been installed on your system. To do so, enter the following command:

pkginfo | grep SUNWiq

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

pkgparam -v packageName | grep PRODVERS

where packageName is any of the MQ packages. The package version is the value of SUNW_PRODVERS.

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 MQ bundled with Sun ONE 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 MQ: DOM4J, Apache Commons Logging

README
(not installed)

README text file

/usr/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)

/usr/share/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

/usr/share/lib/imq/

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

/usr/share/
javadoc/imq/

Contains the MQ 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 MQ C clients (Enterprise Edition only)

/opt/SUNWimq/
lib/

Libraries needed to support MQ C clients (Enterprise Edition only)1

/opt/SUNWimq/
demo/C/

Examples for writing C clients (Enterprise Edition only)

1. See 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 MQ product on Solaris from the Sun ONE website.

    To Install MQ 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 MQ product distribution file from the website into an empty, temporary working directory, temp_directory.

    3. The zipped distribution file name depends on the MQ edition and hardware platform:

    Table 2-3  MQ 3.5 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 MQ packages.

    Table 2-4 describes the MQ 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 MQ. 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

    MQ Java client API javadoc and example applications

    Needed only for Java client development.

    5

    SUNWiqfs

    MQ 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

    MQ Java API for XML Messaging (JAXM): API and runtime

    Required to support Java clients using SOAP/JAXM API.

    7

    SUNWiqlpl or SUNWiqlen

    MQ license files for Platform or Enterprise Edition message server

    Depends on MQ edition.

    8

    SUNWiqr

    MQ message server root package

    Needed for MQ 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

    MQ message server and administration tools

     

    11

    SUNWiquc

    MQ Java API for JMS messaging and Java client runtime.

    Required to support Java clients using JMS API.

    12

    SUNWiqum

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

    1. This package is shared by a number of Sun ONE 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

    MQ message server and administration tools

    SUNWiqr

    SUNWiqu

    SUNWiqlpl or SUNWiqlen

    SUNWiquc

    SUNWjhrt (optional)

    SUNWiqfs (optional)

    Required for a MQ 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 MQ 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 MQ 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 MQ message server.

    The MQ 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 MQ 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-MQ-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 MQ 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 MQ solaris bundle:

    1. Remove the old patches:

      2. #patchrm 114045-XX (sparc)
      #patchrm 114049-XX (sparc)
                              //use actual patch # shown in showrev -a

      or

      #patchrm 114046-XX (i386)
      #patchrm 114050-05 (i386)

    2. Install the patches back

      3. #cd mq3_5-<edition>/patches

      #patchadd 114045-xx (sparc)

      or

      #patchadd 114046-xx (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 MQ 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),
    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 MQ. 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 MQ broker instance as the owner with privileges to the /var/imq/instances/instanceName directory. (You can do this using the -name instanceName option.) As an alternative, you can log in as root and change the privileges on the directory. See the MQ Administrator’s Guide for more information.

Installing from CD-ROM

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

Note

A compressed installation file (zip) is provided on the CD if you do not want to install MQ directly from the packages on the CD.

    To Install MQ 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 MQ 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.".

Configuring MQ for Automatic Startup

If you wish to set the broker (the MQ 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 MQ Administrator’s 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 MQ initialization script (S52imq) in “debug” mode:

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

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:

  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

MQ 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 to Enterprise Edition 3.5, but you cannot upgrade from Platform Edition 3.0.1 to Enterprise Edition 3.5

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 MQ 3.5 modules already installed and does not modify the configuration of your MQ 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

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

1. This is a shared package.

    To Upgrade to Enterprise Edition on Solaris
  1. Stop any running brokers.

    2. imqcmd shutdown bkr -u name -p password [-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 MQ Release Notes files.

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

To uninstall the product, see the following section.

Uninstalling MQ on Solaris

The following instructions explain how to uninstall MQ.

    To Remove MQ on Solaris
  1. Stop any running client applications.
  2. Stop any running brokers.

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

  3. If you want to delete 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.

    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 8.
  5. Find the zipped distribution file used to install MQ (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 MQ 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 MQ packages that are not shared, if any, that are currently installed. (It does not list shared MQ packages installed with MQ, 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 MQ 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 MQ packages, using the following command:

    14. pkgrm packageName

    where packageName is any of the MQ packages. To remove multiple packages, separate the package names by a space.

    Because other products might be using MQ 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 2003 Sun Microsystems, Inc. All rights reserved.