Sun Java System Message Queue 4.2 Installation Guide

Installation Procedure

You can run the Message Queue Installer in any of three modes:

The following sections describe each of these three modes of Installer operation.

Installing in GUI Mode

The following procedure shows how to use the Message Queue Installer in GUI mode to install the Message Queue 4.2 product on your Solaris system.

ProcedureTo Install Message Queue in GUI Mode

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

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

  3. 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_1-installer-SunOS.zip
    

    (for the SPARC platform) or

       mq4_1-installer-SunOS_X86.zip
    

    (for the x86 platform).

  4. Go to the temporary directory.

    Enter the command

       cd tempDir
    

    where tempDir is the temporary directory to which you downloaded the Installer in step 3.

  5. Decompress the Installer archive.

    Enter the command

       unzip mq4_1-installer-SunOS.zip
    

    or

       unzip mq4_1-installer-SunOS_X86.zip
    

    depending on your platform. This creates a subdirectory named

       mq4_1-installer
    

    containing the files needed for Message Queue 4.2 installation.

  6. Switch to the Installer subdirectory.

    Enter the command

       cd mq4_1-installer
    
  7. Start the Installer.

    Enter the command

       installer
    

    The Installer’s Welcome screen (Figure 2–1) appears.

    Figure 2–1 Installer Welcome Screen

    Screen capture showing Message Queue Installer’s
Welcome screen.

  8. Click the Next button.

    The Installer’s License screen (Figure 2–2) appears.

    Figure 2–2 Installer License Screen

    Screen capture showing Message Queue Installer’s
License screen.

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

    1. Read the product license agreement.

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

    3. Click the Next button.

      The Installer’s JDK Selection screen (Figure 2–3) appears.

      Figure 2–3 Installer JDK Selection Screen

      Screen capture showing Message Queue Installer’s
JDK Selection screen.

  10. Specify the version of the Java SDK for Message Queue to use.

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

    2. Click the Next button.

      The Installer’s Multilingual Packages screen (Figure 2–4) appears.

      Figure 2–4 Installer Multilingual Packages Screen

      Screen capture showing Message Queue Installer’s
Multilingual Packages screen.

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

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


      Caution – Caution –

      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.


    2. Click the Next button.

      The Installer’s Upgrade screen (Figure 2–5) appears.

      Figure 2–5 Installer Upgrade Screen

      Screen capture showing Message Queue Installer’s
Upgrade screen.

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


    Caution – Caution –

    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:

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

    2. Click the Next button.

      The Installer’s Ready screen (Figure 2–6) appears.

      Figure 2–6 Installer Ready Screen

      Screen capture showing Message Queue Installer’s
Ready screen.

  13. Click Install to begin the installation.

    The Installer’s Progress screen (Figure 2–7) appears, tracking the progress of the installation as it proceeds.

    Figure 2–7 Installer Progress Screen

    Screen capture showing Message Queue Installer’s
Progress screen.

    When installation is complete, the Installer's Sun Connection Registration screen (Figure 2–8) appears.

    Figure 2–8 Sun Connection Registration Screen

    Screen for Sun Connection registration.

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

    Figure 2–9 Create Sun Online Account Screen

    Screen for creating a Sun Online account.


    Note –

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

    Figure 2–10 Installer Summary Screen

    Screen capture showing Message Queue Installer’s
Summary screen.

    You can click the links on this screen for a detailed summary report and a log file giving more details on the installation.

  15. Click the Exit button to dismiss the Summary screen.

    Message Queue installation is now complete.


    Tip –

    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 command

       imqbrokerd  -version
    

    The output from this command identifies the versions of Message Queue and the Java SDK that are installed on your system.


Installing in Text Mode

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.

Figure 2–11 Installer Welcome Screen in Text Mode

Screen capture showing Message Queue Installer’s
Welcome screen displayed as plain text in the terminal window.

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.

Installing in Silent Mode

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.

Manually Configuring the Java Runtime Environment

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:

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

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

  3. The IMQ_JAVAHOME environment variable.

  4. The environment variable IMQ_DEFAULT_JAVAHOME in the imqenv.conf file.

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

Configuring Message Queue for Automatic Startup

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

   env DEBUG=1 /etc/init.d/imq  start