This chapter covers the following topics as they apply to a Solaris installation of Message Queue 3.7 UR1:
In order to install Message Queue 3.7 UR1, your Solaris system (SPARC or x86) should satisfy the minimum hardware and software requirements shown in Table 2–1.
Table 2–1 Hardware and Software Requirements (Solaris)
Component |
Requirements |
---|---|
CPU |
Sun UltraSPARC Intel Pentium 2 (or compatible) |
RAM |
256 MB |
Disk Space |
SPARC platform:
x86 platform:
Note – The installed product may require more space if the broker stores persistent messages locally. |
Operating System |
Solaris 9 Solaris 10 Note – To ensure proper operation of Message Queue 3.7 UR1, you should install all required Solaris Patches for Java 2 Platform, Standard Edition 5.0. For the latest information about required and recommended patches and to download the patches, see http://java.sun.com/j2se/1.5.0/download.jsp |
Java 2 Platform, Standard Edition (J2SE) |
See Supported Platforms and Components for supported versions of the Java Runtime Environment (JRE) and Java Software Development Kit (JDK). Note – The Message Queue 3.7 UR1 software distribution includes the required JRE version at the time of release. |
The Message Queue 3.7 UR1 product can be downloaded from the Sun Java System Web site. Message Queue also depends on components that you must install in order to develop and run Message Queue clients. See Table 1–1 and Table 1–2 for more information.
Because Message Queue is installed with other products (such as Solaris 9, Solaris 10, and Sun Java System Application Server), you should check whether Message Queue has already been installed on your system. To do so, enter the following command:
imqbrokerd -version
If Message Queue is already installed, the version number is displayed.
If you find that a previous installation already exists on your system, see Upgrading From Previous Versionsfor information on upgrading to Message Queue 3.7 UR1.
To upgrade from Message Queue Versions 3.0.x, 3.5, and 3.6, you need not uninstall those versions; they will be overwritten.
If you want to upgrade to Message Queue 3.7 UR1, you must purchase Message Queue 3.7 UR1 and use the Sun Java Enterprise System installer to upgrade your version of Message Queue. See the Sun Java Enterprise System Installation Guide for more information.
Table 2–2 shows the installed directory structure for a full installation of Message Queue 3.7 UR1 on the Solaris platform. (The directory structure may vary if you perform a partial installation.)
File locations for Message Queue bundled with Sun Java System Application Server may differ from those shown in the table.
A zone is a Solaris Container technology that provides separate environments on a machine and logically isolates applications from one another. Zones allow you to create virtual operating system environments within an instance of the Solaris operating system. Running applications in different zones allows you to run different instances or different versions of the same application on the same machine while, at the same time, permitting centralized administration and efficient sharing of resources.
This section provides a brief description of zones and describes their use with Message Queue 3.7 UR1.
A zone environment includes a global zone and one or more non-global zones. When Solaris 10 is first installed on a system there is only one global zone. An administrator can create other non-global zones as children of the global zone. Each zone appears as an independent system running Solaris. Each zone has its own IP address, own system configuration, own instances of running applications, and its own area on the file system.
The global zone contains resources that can be shared among non global zones; this allows the centralization of certain administrative functions. For example, packages installed in the global zone are available (propagated) to all existing non-global zones. This enables you to centralize life-cycle management like installation, upgrade, and uninstallation. At the same time, the isolation provided by non-global zones results in greater security and allows you to have differently configured instances or different versions of the same application running on the same machine.
Non-global zones are either whole root zones or sparse root zones: which of these you choose as an environment for an application depends on how you want to balance administrative control with resource optimization.
Whole root zones contain a read/write copy of the file system on the global zone. Packages installed in the global zone are automatically copied (with their registry information) to the whole root zones. This maximizes administrative control, at the expense of resources.
Sparse root zones contain a read/write copy of a portion of the file system on the global zone; other file systems are mounted as read-only file systems. Packages installed in the global zone are available to sparse root zones by means of read-only file systems and through the automatic synchronization of registry information. Sparse root zones optimize resource sharing at the cost of centralized administration.
The components that make up the Java Enterprise System depend on some shared components; this creates some limitations in working with zones. In a zones environment, shared components are governed by the following rules.
All shared components within a zone must be of the same JES version. This requirement has three consequences.
If you want to install different versions of shared components, each version must reside in a separate zone.
Within a zone, if a shared component is upgraded or a later version is installed then all shared components must be upgraded.
When you install shared components in the global zone, you must take care that shared components in non global zones are upgraded if necessary.
Shared components cannot be installed in sparse root zones because of the read/only file system in sparse root zones. Instead, they must be installed in the global zone. Those product components that depend on shared components must first be installed in the global zone and then propagated into non-global zones.
These requirements affect the installation of Message Queue because it is a component product of Java Enterprise System and, as such, is limited in its use of zones.
The Message Queue product is installed into the /usr directory and must therefore be installed or upgraded in the global zone first.
When Message Queue is installed in the global zone, it is set to propagate into all of the non-global zones. After installing Message Queue in the global zone, you will have the same version of Message Queue installed in all zones: if you log into any zone and run the command pkginfo -l SUNWiqu, you will see it installed, and it will be the same version as in the global zone. You can then run independent instances of the Message Queue broker in each zone since they do not share the instance and configuration data kept in /var and /etc. Most other Java Enterprise System components are not propagated if they are installed in the global zone.
Because Message Queue is propagated into non-global zones, the global instance is forever linked to the installations in the non-global zones. Therefore, any time you uninstall or upgrade Message Queue in the global zone it will impact instances running in the non-global zones. The following example shows how this might cause unintended results.
You install Message Queue 3.7 UR1 in the global zone. This results in the Message Queue 3.7 UR1 packages also being installed into all non-global zones.
You uninstall Message Queue 3.7 UR1 in a whole root zone. Then, you install Message Queue 3.6 in the whole root zone.
You now have different versions of Message Queue running in different zones, which is a set up you might find useful.
You uninstall Message Queue 3.7 UR1 in the global zone. This will uninstall Message Queue from all other zones - including the Message Queue 3.6 instance in the whole root zone.
Always be aware of the cascading effect of installing or uninstalling Message Queue in the global zone.
The following two use-cases explain how you install different instances and different versions of Message Queue in different zones.
If you want to install Message Queue in a whole root zone on Solaris 10, Solaris 10U1, or Solaris 10U2, you must upgrade Lockhart in the global zone first. See the workaround for bug 645030 for additional information.
Install the desired version of Message Queue in the global zone.
These versions will be propagated into any existing non-global zone. If you create additional non-global zones, Message Queue will also be propagated into these zones. Please note that you can install different instances in whole root zones as well as sparse root zones, but using sparse root zones allows you to make more efficient use of disk space and other resources.
If you want Message Queue to be propagated into any other non-global zones, create these zones now.
Run an instance of Message Queue in each non-global zone.
Uninstall Message Queue from the global zone.
Create whole root zones and configure each zone not to share the /usr directory by using the following directive when you create the zone
remove inherit-pkg-dir dir=/usr
Install different versions of Message Queue in each whole root zone.
Remember that installing or uninstalling Message Queue in the global zone will affect all instances (and versions) of Message Queue running in whole root zones.
The following table describes the Message Queue Solaris packages, and Table 2–4 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–3 Packages in Solaris Bundle
The following table provides a guide to the packages you need for different use scenarios.
Table 2–4 Packages Required for Various Scenarios
Scenario |
Packages Needed |
Notes |
---|---|---|
Message Queue message server and administration tools |
SUNWiqr SUNWiqu SUNWiqlpl SUNWiquc SUNWjhrt SUNWiqfs (optional) |
Required for a Message Queue broker to run on a host. |
Developing and/or deploying Java clients using the JMS API |
SUNWiquc SUNWiqdoc (optional) |
Can be installed on a system without a Message Queue broker. |
Developing and/or deploying Java clients using the SOAP/JAXM API |
SUNWjaf SUNWjmail SUNWiqjx SUNWxsrt SUNWjaxp SUNWiqdoc (optional) |
Can be installed on a system without a Message Queue broker. 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 broker. The Message Queue Message Transformer API depends on both the JMS and SOAP APIs. |
Developing and/or deploying C clients |
SUNWiqcrt SUNWiqcdv SUNWpr SUNWprx SUNWtls SUNWtlsx SUNWtlsu SUNWtlsux (for SSL) |
The SUNWprx, SUNWtlsx, and SUNWtlsux packages on the Solaris SPARC platform are legacy packages and are no longer used. The SUNWtlsu and SUNWtlsux packages are used to create and manage NSS certificate database files by a C client when using SSL. |
The following instructions explain how to download and install the Message Queue product on Solaris from the Sun Java System Web site.
Read the product license. Installation and use of the product are subject to acceptance of the license agreement.
Download the Message Queue product distribution file from the Web site into an empty, temporary working directory, temp_directory.
The zipped distribution file name depends on the Message Queue hardware platform:
Edition |
SPARC |
x86 |
---|---|---|
Platform |
mq3_7-ent-solsparc.zip |
mq3_7-ent-soli386.zip |
Change to a temporary directory.
cd temp_directory
Unzip the distribution file.
unzip mq3_7-ent-platform.zip
where platform is either solsparc or soli386, depending on the platform.
The unzip command creates an mq3_7-ent directory which contains the distribution files: LICENSE, ENTITLEMENT, DISTRIBUTIONREADME, THIRDPARTYLICENSECREADME, README, 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 9 (SunOS5.9).
Table 2–3 describes the Message Queue packages, and Table 2–4 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.
Change to the directory containing the Message Queue distribution files.
cd mq3_7-ent
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 Table 2–3
./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 that do not begin with SUNWiq and that 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 /var/sadm/install/logs/ directory.
Check your system for patches to any of the shared packages listed in table Table 2–3 (packages that do not begin with SUNWiq and that might already be installed on your system). Look in the following directory to see what versions will be installed:
./pkgs/Solaris_versNo/pkg_name/pkginfo
Then, find the current installed version of the shared component using a command like the following:
% pkgparam -v pkg_name | grep VERSION
or
% pkgparam -v pkg_name | grep SUNW_PRODVERS
If there is no package already installed, then you can go ahead and install the new one.
If an existing package is older than the new one, remove the older one using the pkgrm command. For example,
% pkgrm SUNWpr
Then, add the new packages as shown in Step 10.
If the package version is the same, don't add or remove anything.
If you want to install a subset of the packages listed in table Table 2–3, if you want to install shared packages, or if you do not want to overwrite later versions of packages, do the following:
Change to the pkgs directory
cd pkgs
Run the pkgadd command to install the packages you want. Note the special directions below for upgrading shared components.
pkgadd -d ./ -a admin.conf
The pkgadd utility lists the names of all packages in the directory available for installation (see Table 2–3). When prompted, indicate the packages you want to install, by entering the number of the package. To select multiple packages, enter a list of numbers separated by a comma.
(The-a admin.conf option permits an overwrite of any packages that are already installed on your system.) The pkgadd utility installs the packages you specify, possibly asking for additional information, and eventually returns to the original prompt, displaying the list of packages available for installation. Please note that running the pkgadd command from the ./pkgs directory with the default selection (all), will install all the Message Queue packages as well, which are already installed by the mqinstall script
To upgrade shared components (indicated by a package name that does not start with SUNWiq), you must also run the command pkgadd -d from the ./pkgs/Solaris_9 directory or the ./pkgs/Solaris_10 directory, depending on the operating system where you are installing the product. (This directory contains operating-system-specific shared components only). For example, the following command adds the shared components that are needed in Solaris 10.
cd pkgs/Solaris_10 pkgadd -d ./ -a ../admin.conf
Type q to quit.
Exit the root shell.
Back up the zip distribution file from your temporary working directory.
This is your logical media. You will need it to uninstall or reinstall Message Queue. Treat this file as you would any other installation media and place a copy in a safe location.
The instance data for any pre-existing broker instance (including the default broker instance, named imqbroker) is owned by the user that 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.
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.
If you want to set the broker (the Message Queue message server) for automatic startup, you need to become root and to edit the configuration file /etc/imq/imqbrokerd.conf. The startup properties you can set in this configuration file are shown in the following table.
Table 2–5 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 Command Utility in Sun Java System Message Queue 3.7 UR1 Administration Guidefor a listing and description of imqbrokerd command line options. (For example -name instanceName.) |
RESTART |
Specifies (YES/NO) if the broker is automatically restarted 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 in debug mode by using the following command:
env DEBUG=1 /etc/init.d/imq start
At startup, the Message Queue broker 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 you specify both, 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 latest JDK installed on the system.
To check which version the broker is using, you can start the broker with the following command: imqbrokerd -verbose
The following instructions explain how to uninstall Message Queue.
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 properties 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 and place it in a temporary directory, temp_directory.
Change directories to temp_directory:
cd temp_directory
Unzip the distribution file.
unzip mq3_7-ent-platform.zip
where platform is solsparc or soli386, depending on the platform.
Change to the directory containing the Message Queue packages.
cd mq3_7-ent
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 specifies a Message Queue package. To remove multiple packages, separate the 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 (yes).
Type q to quit.
Exit the root shell.
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 documentation Web site.
For an overview of Sun Java System 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 IMQ_HOME/javadoc directory.