This chapter covers the following topics as they apply to a Solaris installation of Message Queue 4.3:
In order to install Message Queue 4.3, your Solaris system should satisfy the minimum hardware requirements shown in Table 2–1. See Supported Platforms and Components for information on software requirements.
Table 2–1 Minimum Hardware Requirements for Solaris Installation
Because Message Queue is installed with other products (such as Solaris 9, Solaris 10, and Sun JavaTM System Application Server), you should check whether it has already been installed on your system. To do so, enter the command
imqbrokerd -version
If Message Queue is already installed, its version number will be displayed. The Message Queue 4.3 Installer will upgrade automatically to Version 4.3 from any Version 3.6 or later. If you have a version earlier than 3.6 installed, you will need to uninstall it before running the Message Queue 4.3 Installer.
The Message Queue 4.3 Installer does not share the same product registry with other installers, such as those of the Sun Java Enterprise System (JES) and Sun Java System Application Server, which include Message Queue as a component. The Message Queue Installer also installs or upgrades shared software components that Message Queue depends on, such as the Java Software Development Kit (SDK), Netscape Portable Runtime (NSPR), Network Security Services (NSS), and JavaHelp. Using this Installer to upgrade an earlier version of Message Queue that was installed with another installer may upgrade such shared components without correctly updating their version numbers in the other installer’s product registry, leaving that registry in an inconsistent state.
If you later run the other installer, the inconsistent registry entries may in turn cause that installer to inadvertently remove Message Queue 4.3. The safest and cleanest way to upgrade an earlier version of Message Queue that was installed with a different installer is as follows:
Use the other installer’s uninstaller to remove Message Queue.
Use the Message Queue 4.3 Installer to install Message Queue 4.3.
You can run the Message Queue Installer in any of three modes:
In GUI (graphical user interface) mode, the Installer presents a series of graphical screens with which you interact using mouse clicks and keyboard text entry.
In text mode, the Installer uses plain text displayed directly in your terminal window to simulate the appearance of the GUI screens. Instead of the mouse, you use keyboard keys such as Tab, Return, and arrow keys to interact with these screens. This is convenient for situations in which you do not have access to a windowing system to display the Installer’s full graphical user interface.
In silent mode, the Installer operates from a predefined answer file representing your responses to the GUI screens. This allows you to script the installation process in advance and then perform it in batch mode without actually displaying the GUI (or text) screens and responding to them interactively.
The following sections describe each of these three modes of Installer operation.
The following procedure shows how to use the Message Queue Installer in GUI mode to install the Message Queue 4.3 product on your Solaris system.
Become the root user.
You must have root user privileges to run the Message Queue Installer. Enter the command
su
and provide a valid root user password when prompted to do so.
Create a temporary directory.
From your system’s command line, enter the command
# mkdir tempDir
where tempDir is any name you choose for your temporary directory.
Download the Message Queue Installer to the temporary directory.
The Installer is available for download from the Message Queue product Web site at
http://www.sun.com/software/products/message_queue
It is distributed as a compressed archive (.zip) file named
mq4_3-installer-SunOS.zip
(for the SPARC platform) or
mq4_3-installer-SunOS_X86.zip
(for the x86 platform).
Go to the temporary directory.
Enter the following command:
# cd tempDir
where tempDir is the temporary directory to which you downloaded the Installer in step 3.
Decompress the Installer archive.
Enter the following command:
# unzip mq4_3-installer-SunOS.zip
or
# unzip mq4_3-installer-SunOS_X86.zip
depending on your platform. This creates a subdirectory named
mq4_3-installer
containing the files needed for Message Queue 4.3 installation.
Switch to the Installer subdirectory.
Enter the following command:
# cd mq4_3-installer
Start the Installer.
Enter the following command:
# installer
The Installer’s Welcome screen (Figure 2–1) appears.
Click the Next button.
The Installer’s License screen (Figure 2–2) appears.
Read and accept the product license agreement.
Installation and use of the Message Queue product are subject to your acceptance of the license agreement. You must read and accept the terms of the license agreement before installing the product.
Read the product license agreement.
Make sure the radio button labeled “I accept the terms in the license agreement” is selected.
If you instead select “I do not accept the terms in the license agreement,” the Next button becomes disabled. You cannot proceed with installation without accepting the license terms.
Click the Next button.
The Installer’s JDK Selection screen (Figure 2–3) appears.
Specify the version of the Java SDK for Message Queue to use.
Select a Java SDK.
You can do this in any of three ways:
Install the default SDK.
Select the option labeled “Install and use the default version of the Java SDK.”
Choose an SDK already installed on your system.
The drop-down menu under the option “Choose a Java SDK from the list below” lists existing SDKs found in standard locations on your system. You can use this option to specify one of these SDKs for Message Queue to use.
Provide an explicit path to an existing SDK.
To use an SDK from a location other than the standard ones, enter its path in the text field under the option “Type in a Java SDK location below,” or use the button marked with an ellipsis (…) to browse to it interactively.
Click the Next button.
The Installer’s Multilingual Packages screen (Figure 2–4) appears.
Specify whether to install multilingual packages.
By default, Message Queue is installed to operate in the English language only. The Multilingual Packages screen allows you to install it for use in another language.
If you will be using Message Queue in a language other than English, select the checkbox labeled “Install Message Queue multilingual packages.”
If you will be using Message Queue only in English, leave this checkbox deselected.
If you choose not to install the multilingual packages and later decide that you do need them after all, there is no convenient way to install them incrementally: you will have to uninstall Message Queue and then repeat the entire installation procedure with the multilingual packages selected. Before proceeding to install without the multilingual packages, be sure you will not be needing them in the future.
Click the Next button.
The Installer’s Upgrade screen (Figure 2–5) appears.
Specify whether to upgrade Message Queue and its shared components.
If an earlier version of Message Queue exists on your system, or if any of the shared components on which Message Queue depends need to be upgraded from earlier versions, the Upgrade screen displays them in a scrollable list along with their current and required versions. If no upgrades are needed, the existing components are simply listed with their version numbers and a notation that they will remain at their current versions. In this case, the “Upgrade” and “Do not upgrade” radio buttons do not appear; just click Next to proceed to the next step.
It is possible that upgrading Message Queue’s shared components may break other software components on your system that depend on the earlier versions previously installed. Be sure there are no such dependencies before proceeding with the upgrade.
To proceed with the upgrade:
Make sure the radio button labeled “Upgrade” is selected.
If you instead select “Do not upgrade,” the Next button becomes disabled; your only options at this point are Back (to return to the previous screen) or Cancel (to exit the Installer without completing installation).
Click the Next button.
The Installer’s Ready screen (Figure 2–6) appears.
Click Install to begin the installation.
The Installer’s Progress screen (Figure 2–7) appears, tracking the progress of the installation as it proceeds.
When installation is complete, the Installer's Sun Connection Registration screen (Figure 2–8) appears.
Register Message Queue with Sun Connection.
Sun Connection is a Sun-hosted service that helps you track, organize, and maintain Sun hardware and software. When you register a Message Queue installation with Sun Connection, information such as the release version, host name, operating system, installation date, and other such basic information is securely transmitted to the Sun Connection database. The Sun Connection inventory service can help you organize your Sun hardware and software, while the update service can inform you of the latest available security fixes, recommended updates, and feature enhancements.
Registration requires that you have a Sun Online account or create one. If you do not already have an account, the installer provides the following screen (Figure 2–9) for creating a Sun Online account:
If you choose not to register Message Queue during installation, you can subsequently register Message Queue by running the installer in register-only mode, as follows:
# installer -r
The register-only mode requires that Message Queue 4.3 already be installed and will display only the installer screens related to registration.
When Sun Connection registration is complete, the Installer’s Summary screen (Figure 2–10) appears, summarizing the steps that were performed during installation.
You can click the links on this screen for a detailed summary report and a log file giving more details on the installation.
Click the Exit button to dismiss the Summary screen.
Message Queue installation is now complete.
After installation is complete, you can check that the expected versions of Message Queue and the Java runtime have been installed by navigating to the Message Queue /bin directory and executing the following command:
# imqbrokerd -version
The output from this command identifies the versions of Message Queue and the Java SDK that are installed on your system.
For situations in which you do not have access to a windowing system to display the Installer’s full graphical user interface, the Message Queue Installer provides an alternate text mode that simulates the operation of the GUI using plain text displayed directly in your terminal window. For example, Figure 2–11 shows the text-mode counterpart of the Welcome screen shown earlier in Figure 2–1. Instead of clicking the Next button with the mouse, you would use the Tab key to advance the cursor to that button, then select it by pressing Return.
To start the Installer in text mode, use the -t option when invoking it from the command line:
# installer -t
The rest of the installation process is essentially the same as described above under To Install Message Queue in GUI Mode, except that instead of the mouse, you must use keyboard keys such as Tab, Return, and arrow keys to select the various elements of the Installer screens.
In silent mode, the Installer operates from a predefined answer file representing your responses to the GUI screens. This allows you to script the installation process in advance and then perform it in batch mode without actually displaying the GUI screens and responding to them interactively.
To create an answer file, start the Installer with the -n option:
# installer -n answerFile
where answerFile identifies the file in which to record your responses. This causes the Installer to execute a “dry run,” presenting the sequence of GUI screens without actually performing the installation. Your input responses are recorded in the specified answer file. You can then perform the installation at a later time by starting the Installer with the -s (“silent”) option, specifying the same answer file:
# installer -s -a answerFile
This performs a silent installation as defined by the answer file, without visibly displaying the GUI (or text) screens.
The Message Queue Installer’s JDK Selection screen is not the only way to specify a version of the Java Runtime Environment for Message Queue to use. The JRE used by the Message Queue command line utilities (imqadmin, imqbrokerd, imqcmd, imqobjmgr, imqdbmgr, imqusermgr, imqkeytool) is determined by the following sources, in order of precedence:
The -jrehome or -javahome command line option to the imqbrokerd command. (If both are specified, the one occurring last on the command line takes precedence).
The J2SE file location specified in the jdk.env file. (This file is deprecated, but is still supported for backward compatibility. For historical reasons, it has higher priority than anything else except option 1.)
The IMQ_JAVAHOME environment variable.
The environment variable IMQ_DEFAULT_JAVAHOME in the imqenv.conf file.
The system default locations, as specified in the documentation for your platform.
To check which version of the Java runtime Message Queue will use, enter the command
# imqbrokerd -version
The output from this command includes the version and pathname of the configured JRE: for example,
Java Runtime: 1.5.0_12 Sun Microsystems Inc. /usr/jdk/instances/jdk1.5.0/jre
When you specify a JRE location through the Installer’s JDK Selection screen, the Installer saves that location as the value of IMQ_DEFAULT_JAVAHOME in the imqenv.conf file (option 4 in the list above). On Solaris, this file is located at
/etc/imq/imqenv.conf
After a successful Message Queue installation, it should include something like the following:
IMQ_DEFAULT_JAVAHOME=/usr/jdk/jdk1.5.0_12
You can override this setting, however, either by editing the imqenv.conf file or by setting one of the other options higher in the list. This can be useful, for instance, for testing or reconfiguring the broker when a newer JRE version becomes available. Understanding how the JRE is determined can also help in troubleshooting problems. For instance, if the imqbrokerd -version command shows that Message Queue is using an unexpected JRE, it may be that one of the higher-precedence options has been set inadvertently (such as by an old jdk.env file that should have been deleted).
To configure the Message Queue message broker to start up automatically at boot time, become the root user and edit the configuration file /etc/imq/imqbrokerd.conf. Table 2–2 shows the startup properties you can set in this file.
Table 2–2 Configuration Properties for Automatic Startup
Property Name |
Values |
Default Value |
Description |
---|---|---|---|
AUTOSTART |
YES NO |
NO |
Start broker automatically at boot time? |
ARGS |
String |
None |
Command line options and arguments for broker startup command See the section “Broker Utility” inChapter 15, Command Line Reference, in Sun Java System Message Queue 4.3 Administration Guide for Broker Utility command line options. |
RESTART |
YES NO |
YES |
Restart broker automatically on abnormal exit? |
To check that startup changes are correct without booting the system, you can, as the root user, explicitly run the Message Queue initialization script in debug mode with the following command:
# env DEBUG=1 /etc/init.d/imq start
Table 2–3 lists the packages used by Message Queue on the Solaris platform.
Table 2–3 Message Queue Packages (Solaris)
Name |
Description |
---|---|
Message Queue Product |
|
SUNWiqr |
Message Queue root package (configuration files) |
SUNWiqu |
Message Queue broker runtime |
SUNWiqlen |
Message Queue commercial product broker |
SUNWiquc |
Message Queue Java client runtime |
SUNWiqfs |
Message Queue Java Naming and Directory Interface (JNDI) File System Service Provider |
SUNWiqjx |
Message Queue Java API for XML Messaging (JAXM) client runtime |
SUNWiqum |
Message Queue JMS/SOAP Message Transformer |
SUNWiqdoc |
Message Queue Java client API JavaDoc and example applications |
SUNWiqcdv |
Message Queue C client development (API header files and demo files) |
SUNWiqcrt |
Message Queue C client runtime |
SUNWiqinst |
Message Queue Installer metadata |
Message Queue Multilingual Packages |
|
SUNWfiqu |
Message Queue broker runtime for French language |
SUNWfiquc |
Message Queue Java client runtime for French language |
SUNWeiqu |
Message Queue broker runtime for Spanish language |
SUNWeiquc |
Message Queue Java client runtime for Spanish language |
SUNWdiqu |
Message Queue broker runtime for German language |
SUNWdiquc |
Message Queue Java client runtime for German language |
SUNWhiqu |
Message Queue broker runtime for Traditional Chinese |
SUNWhiquc |
Message Queue Java client runtime for Traditional Chinese |
SUNWciqu |
Message Queue broker runtime for Simplified Chinese |
SUNWciquc |
Message Queue Java client runtime for Simplified Chinese |
SUNWjiqu |
Message Queue broker runtime for Japanese language |
SUNWjiquc |
Message Queue Java client runtime for Japanese language |
SUNWkiqu |
Message Queue broker runtime for Korean language |
SUNWkiquc |
Message Queue Java client runtime for Korean language |
J2SETM Development Kit (JDK) |
|
SUNWj5rt |
Java platform virtual machine and core class libraries |
SUNWj5rtx |
Java platform virtual machine and core class libraries (64–bit) |
SUNWj5cfg |
Java platform host-specific configuration |
SUNWj5dev |
Java platform development tools |
SUNWj5dvx |
Java platform development tools (64–bit) |
SUNWj5man |
Java platform manual pages |
SUNWj5jmp |
Java platform manual pages (Japanese language) |
SUNWj5dmo |
Java platform demonstration applications and applets |
SUNWj5dmx |
Java platform demonstration applications and applets (64–bit) |
NSPR/NSS |
|
SUNWpr |
Netscape Portable Runtime (NSPR) interface |
SUNWtls |
Network Security Services (NSS) libraries |
SUNWtlsu |
Network Security Services (NSS) utilities |
Sun Installation Framework |
|
SUNWinstall-engine-core |
Sun installation software support files |
SUNWinstall-resources |
Sun installation software resources |
JavaHelp |
|
SUNWjhrt |
JavaHelp runtime |
SUNWjhdev |
JavaHelp developer toolkit |
SUNWjhdoc |
JavaHelp documentation |
SUNWjhdem |
JavaHelp demos |
Table 2–4 shows the installed directory structure for a full installation of Message Queue 4.3 on the Solaris platform.
The directory structure may vary if you have installed Message Queue as part of a Sun Java System Application Server installation.
Zones are a SolarisTM Containers technology, introduced in Solaris 10, that provides separate operating 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.
A zone environment includes a global zone and one or more nonglobal zones. When Solaris 10 is first installed on a system, there is only a single, global zone. An administrator can then create one or more nonglobal zones as children of the global zone. Each zone appears as an independent system running Solaris, with its own IP address, system configuration, instances of running applications, and area of the file system.
The global zone contains resources that can be shared among nonglobal zones. This allows the centralization of certain administrative functions: for example, packages installed in the global zone are available (propagated) to all existing nonglobal zones. This enables you to centralize life-cycle management like installation, upgrade, and uninstallation. At the same time, the isolation provided by nonglobal 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.
Nonglobal zones are of two types: whole-root and sparse-root. Which of these you choose as an environment for an application depends on how you want to balance administrative control with resource optimization.
A whole-root zone contains a read/write copy of the global zone’s file system. Packages installed in the global zone are automatically copied (with their registry information) to the whole-root zone. This maximizes administrative control at the expense of resource sharing.
A sparse-root zone contains a read/write copy of a portion of the global zone’s file system; other file systems are mounted as read-only file systems. Packages installed in the global zone are available to the sparse-root zone 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 Sun Java Enterprise System (JES) depend on some shared components; this creates some limitations in working with zones. As a JES component, Message Queue is subject to these limitations. In a zone 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 nonglobal zones are upgraded if necessary.
Shared components cannot be installed in sparse-root zones because of the read/only file system. 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 to nonglobal zones. In particular, since Message Queue is installed in the /usr directory, it must be installed or upgraded in the global zone first.
For more information on zones and their use in JES, see the following sources:
Sun Java Enterprise System Installation Guide for UNIX, Chapter 2 (“Example Installation Sequences”), section “Solaris 10 Zones Examples”
Sun Java Enterprise System Installation Planning Guide, Appendix A (“Java ES and Solaris 10 Zones”)
When Message Queue is installed in the global zone, it is configured to propagate to all nonglobal zones. After installing Message Queue in the global zone, you will have the same version installed in all zones: if you log into any zone and execute the following command:
# pkginfo -l SUNWiqu
you will see the same version installed 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 the /var and /etc directories. Most other JES components are not propagated if they are installed in the global zone.
Because Message Queue is propagated to nonglobal zones, the global instance is forever linked to the installations in the nonglobal zones. Therefore, any time you uninstall or upgrade Message Queue in the global zone, it will affect instances running in the nonglobal zones. Always be aware of this cascading effect; the following example shows how it might cause unintended results:
You install Message Queue 4.3 in the global zone. This results in the Message Queue 4.3 packages also being installed in all nonglobal zones.
You uninstall Message Queue 4.3 in a whole-root zone.
You install Message Queue 3.7 UR1 in the whole-root zone. You now have different versions of Message Queue running in different zones, a configuration you might find useful.
You uninstall Message Queue 4.3 from the global zone. This will uninstall Message Queue from all other zones, including the Message Queue 3.7 UR1 instance in the whole-root zone.
The following two use cases show how to 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, 10U1, or 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.
This version will be propagated to all existing nonglobal zones. If you create additional nonglobal zones, Message Queue will also be propagated to these zones. 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 to any other nonglobal zones, create these zones now.
Run an instance of Message Queue in each nonglobal zone.
Uninstall Message Queue from the global zone.
This will automatically uninstall it from all nonglobal zones as well.
Create whole-root zones and configure each zone not to share the /usr directory.
Install different versions of Message Queue in each whole-root zone.
Remember that later installing or uninstalling Message Queue in the global zone will affect all instances (and versions) running in whole-root zones.
Like the Installer, the Message Queue Uninstaller can be run in any of three modes of operation:
In GUI (graphical user interface) mode, the Uninstaller presents a series of graphical screens with which you interact using mouse clicks and keyboard text entry.
In text mode, the Uninstaller uses plain text displayed directly in your terminal window to simulate the appearance of the GUI screens. Instead of the mouse, you use keyboard keys such as Tab, Return, and arrow keys to interact with these screens. This is convenient for situations in which you do not have access to a windowing system to display the Uninstaller’s full graphical user interface.
In silent mode, the Uninstaller operates from a predefined answer file representing your responses to the GUI screens. This allows you to script the uninstallation process in advance and then perform it in batch mode without actually displaying the GUI screens and responding to them interactively.
The following sections describe each of these three modes of Uninstaller operation.
The Message Queue installation includes several scripts and executables named uninstaller, both in the Installer .zip bundle and on your system after installation. To uninstall Message Queue 4.3, it is important that you run the correct uninstaller executable, located at
/var/opt/install/contents/mq/uninstaller
Be careful not to invoke some other uninstaller by mistake.
The following procedure shows how to use the Message Queue Uninstaller in GUI mode to uninstall Message Queue 4.3 from your Solaris system.
Become the root user.
You must have root user privileges to run the Message Queue Uninstaller. Enter the following command:
$ su
and provide a valid root user password when prompted to do so.
Set your working directory to the directory containing the Uninstaller.
From your system’s command line, enter the following command:
# cd /var/opt/install/contents/mq
Start the Uninstaller.
Enter the following command:
# uninstaller
The Uninstaller’s Ready screen (Figure 2–12) appears.
Click the Remove button.
The Uninstaller’s Progress screen (Figure 2–13) appears.
When uninstallation is complete, the Uninstaller’s Summary screen (Figure 2–14) appears, summarizing the steps that were performed during uninstallation. You can click the links on this screen for a detailed summary report and a log file giving more details on the uninstallation.
Click the Exit button to dismiss the Summary screen.
Message Queue uninstallation is now complete.
For situations in which you do not have access to a windowing system to display the Uninstaller’s full graphical user interface, the Message Queue Uninstaller provides an alternate text mode that simulates the operation of the GUI using plain text displayed directly in your terminal window. For example, Figure 2–15 shows the text-mode counterpart of the Ready screen shown earlier in Figure 2–12. Instead of clicking the Next button with the mouse, you would use the Tab key to advance the cursor to that button, then select it by pressing Return.
To start the Uninstaller in text mode, use the -t option when invoking it from the command line:
# uninstaller -t
The rest of the uninstallation process is essentially the same as described above under To Uninstall Message Queue in GUI Mode, except that instead of the mouse, you must use keyboard keys such as Tab, Return, and arrow keys to select the various elements of the Uninstaller screens.
In silent mode, the Uninstaller operates from a predefined answer file representing your responses to the GUI screens. This allows you to script the uninstallation process in advance and then perform it in batch mode without actually displaying the GUI screens and responding to them interactively. To create an answer file, start the Uninstaller with the -n option:
# uninstaller -n answerFile
where answerFile identifies the file in which to record your responses. This causes the Uninstaller to execute a “dry run,” presenting the sequence of GUI screens without actually performing the uninstallation. Your input responses are recorded in the specified answer file. You can then perform the uninstallation at a later time by starting the Uninstaller with the -s (“silent”) option, specifying the same answer file:
# uninstaller -s -a answerFile
This performs a silent uninstallation as defined by the answer file, without visibly displaying the GUI (or text) screens.