Chapter 2   Solaris Installation


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

• Hardware and Software Requirements

• Installing MQ on Solaris

• Configuring MQ for Automatic Startup

• Configuring the Java Runtime for MQ

• Upgrading Editions

• Where To Go Next

• Uninstalling MQ on Solaris

Hardware and Software Requirements

---

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

Table 2-1    Hardware and Software Requirements for Solaris 

Component	Requirements
Operating system	Solaris 8 and Solaris 9 (SPARC platforms) 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/install-solaris-patches.html (The MQ software distribution CD includes the solaris/jdk-patches available at the time of release.)
CPU	Sun Ultra™ 1 (or compatible) workstation that is TCP/IP networked
RAM	128 Mbytes
Hard drive space	The compressed installation file is approximately 6 Mbytes. The temporary working directory used for extracting the installation files requires an additional 8 Mbytes. The installed product requires approximately 8 Mbytes of hard drive space. MQ, however, may need more space if the broker stores persistent messages locally.
JVM	1.4 JVM The MQ software distribution CD includes the JRE 1.4 version available 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.

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. Download the MQ product from the website into an empty, temporary working directory.

2. Run the command script:

   sh imq3_0-edition-solsparc.sh

   where edition takes one of the following values: plt or ent, depending on whether you are installing the Platform or Enterprise Edition, respectively.

   The command displays the first page of the license for the product.

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

4. To display the entire license, one page at a time, repeatedly press the space bar. When you reach the end of the license, the program prompts you to accept the license.
   • If you choose not to accept the license agreement, type no or n and the installation terminates.

   • If you choose to accept the license agreement, type yes or y and the installation continues. The following files are extracted:
     • README

     • imq3_0-edition-solsparc.tar.Z

     • COPYRIGHT

     • LICENSE (a copy of the license agreement)

5. Extract the archived files:

   /bin/zcat imq3_0-edition-solsparc.tar.Z | tar xvfp -

   A new directory, imq3_0-pkgs, is created.

   
   

   ---

   Note	To avoid possible problems, do not use the GNU tar utility when installing MQ.

   ---

   
   

6. Change directories:

   cd imq3_0-pkgs

7. Become root:

   su root

8. Run the pkgadd command to install the packages:

   pkgadd -d ./

   The pkgadd utility lists the names of all packages in the directory available for installation (see Table 2-2). When prompted, indicate the packages you want to install.

   In a development environment, you will probably install all packages (except, possibly, SUNWjhrt). In a production environment, however, you only need install SUNWiqu, SUNWiqr, SUNWiqlpl (or SUNWiqlen).

   
   

   Table 2-2    Packages in Solaris Bundle 
   
   

   #	Package	Description	Note
   1	SUNWiqdoc	Sun ONE Message Queue Javadoc and example applications	Optional: needed only for client development
   2	SUNWiqlpl or SUNWiqlen	Sun ONE Message Queue Platform or Enterprise Edition broker	Required: contains license files; depends on MQ edition
   3	SUNWiqr	Sun ONE Message Queue root package	Required: contains libraries needed for MQ executables and client development
   4	SUNWiqsup	Sun ONE Message Queue supplemental package for JDK 1.2 and 1.3	Optional: contains JNDI and JSSE jar files— needed only for client development with JDK 1.2 and 1.3
   5	SUNWiqu	Sun ONE Message Queue /usr package	Required: contains executables and MQ administration tools
   6	SUNWjhrt	JavaHelp runtime	Optional: needed only if not installed with Solaris OS (for example, Solaris 8). This will only install if a JVM 1.4 or greater has first been installed.

   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.

9. Type q to quit.

10. Exit the root shell.

11. Back up the imq3_0-edition-solsparc.sh file from your temporary working directory.

    This is your logical media. Treat this file as you would any other installation media. Place a copy in a safe location in case you encounter a situation (such as a system failure) that requires reinstallation of the product.

12. Clean up all remaining files in your temporary working directory.

    
    

    ---

    Note

    Once installation is complete, to run the default broker instance (named imqbroker), you must be root—or, as root, change the privileges on the /var/imq/instnces/imqbroker directory (where configuration and persistent data are stored). However, if you run a non-default broker instance (using the -name brokerName option) then you automatically have privileges to the /var/imq/instnces/brokerName directory.

    ---

    
    

Installing from CD-ROM

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

---

Note	A compressed installation file (tar.Z) 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.

   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.

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

   If the Volume Manager is not running on your machine:

   • Create a directory called /cdrom/messagequeue3_0 by typing:

        mkdir -p /cdrom/messagequeue3_0

   • Mount the CD-ROM manually:

        mount -rF hsfs cdrom-device /cdrom/messagequeue3_0

   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/ 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_0/solaris/imq3_0-pkgs

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

4. Run the pkgadd command to install the packages:

   pkgadd -d ./

   The pkgadd utility lists the names of all packages in the directory available for installation. When prompted, indicate the packages you want to install (see Table 2-2).

5. When the pkgadd prompt returns, type q to quit.

6. Exit the root shell.

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

Table 2-3    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 brokerName)
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.

   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 Editions

---

MQ comes in two editions, as explained in "Product Editions".

To upgrade from the Platform Edition to the Enterprise Edition, you need to install the Enterprise Edition license. This installation does not overwrite the MQ modules already installed and does not modify the configuration of your MQ messaging system.

To install the Enterprise Edition license you need only the SUNWiqlen package contained in the Enterprise Edition. The SUNWiqlen package is placed automatically in the imq3_0-pkgs directory (Web installation) or in the solaris/imq3_0-pkgs directory (CD-ROM installation) as a result of running the installation command script, uncompressing the file archive, and extracting the archived files.

To upgrade to Enterprise Edition on Solaris

1. Stop any running brokers.

   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. When the installation is finished, add the SUNWjqent package:

   pkgadd -d . SUNWiqlen

4. Verify that the Enterprise Edition license is available by running the following command:

   imqbrokerd -license

Where To Go Next

---

Read the README and MQ Release Notes (relnotes.html) files.

• The README includes information on where to find documentation, news and updates, and how to send feedback.

• The MQ Release Notes contain information on code and documentation changes, open bugs, and important technical notes. This document is available on the Sun ONE website.

For an overview of Sun ONE Message Queue concepts, a brief introduction to writing and compiling a client application, see the MQ 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.

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

3. Unless you want to retain dynamic broker data, remove all data files associated with each broker instance.

   imqbrokerd -name brokerName -remove instance

4. If you wish to preserve the MQ flat file user repository and the MQ access control file, copy the following files to some safe location before removing MQ packages (they can be restored after re-installing or upgrading MQ):

   /etc/imq/passwd

   /etc/imq/accesscontrol.properties

5. Determine which MQ packages are installed.

   To see a list of MQ packages installed on your system using pkgadd, type:

   pkginfo | grep SUNWiq

6. Become root by typing:

   su root

   When prompted, type your root password.

7. Remove the MQ packages that were installed with pkgadd.

   Issue the following command:

   pkgrm <packagename>

   where <packagename> is a package name from the previous list.

   To remove multiple packages, separate the package names by a space.

8. When prompted, confirm your removal request by typing y.