|
| |
| Sun Java System Message Queue 3 2005Q1 Installation Guide | |
Chapter 3
Linux InstallationThis chapter explains the following topics as they apply to a Linux installation of Message Queue 3 2005Q1 (3.6), Platform Edition:
Hardware and Software RequirementsAt a minimum, your Linux system should satisfy the minimum requirements indicated in the following table.
Installing Message Queue on LinuxThe Sun Java System Message Queue product can be downloaded from the Sun Java System website. For hardware and software requirements for component products that can be used with Message Queue, see the Message Queue Release Notes.
Finding and Removing Earlier Message Queue Versions
Because Message Queue is installed with other products (Sun Java System Application Server, and possibly others), you should check whether Message Queue has already been installed on your system, and uninstall it before installing Message Queue 3 2005Q1.
If a 3.0.x or 3.5x version of Message Queue is already on your system, you need to decide if you want to preserve any security-related data (flat-file user repository, access control file, or passfile). If, so, you will need to use the mqmigrate utility, as explained in subsequent paragraphs, before uninstalling the earlier version of Message Queue. If you do not want to preserve your old data files, you do not have to run the mqmigrate utility.
Depending on the version, Message Queue might have been installed using tar files or the Red Hat Package Manager (RPM). To check for installed versions, therefore, you need to check for both. It is recommended that you check first for RPM installations and then for tar file installations.
Migrating Files from Non-Default Locations
The mqmigrate utility provides options that allow you to migrate data that has been installed in a non-default location (only applies to Message Queue 3.0.x data).
The mqmigrate utility uses the following syntax:
mqmigrate [-basedir baseDir]
Table 3-2 shows the data locations for Message Queue installations (with the 3.0.x non-default location in parenthesis). The mqmigrate utility assumes these locations. If Message Queue 3.0.x has been installed in a non-default location, you must use the -basedir option described in Table 3-3 to point the utility to this destination.
Table 3-3 describes the mqmigrate utility -basedir option.
To migrate data to a planned Message Queue 3 2005Q1 installation
- Accept the license agreement on the Message Queue product download site.
- Download the Message Queue product distribution file from the website into an empty, temporary download directory, temp_directory.
The download file is: mq3_6-plt-linx86.zip
- Change to the temp_directory and uncompress the distribution file.
unzip mq3_6-plt-linx86.zip
The unzip command creates a mq3_6-plt directory which contains the distribution files: LICENSE, README, THIRDPARTYLICENSEREADME, and COPYRIGHT files; mqinstall utility; mquninstall utility; mqmigrate utility; and an rpms directory.
- Change to the mq3_6-plt directory.
cd mq3_6-plt
- Login as Root.
su root
- Migrate broker instance data using the following command:
./mqmigrate [-basedir baseDir]
Note
The -basedir option is only required if Message Queue 3.0.x is installed in a non-default installation directory. For more information on this option, see Table 3-3.
Command Examples for mqmigrate Utility
The following command will migrate data from a Message Queue 3.0.x instance in the directory /export to Message Queue 3 2005Q1 locations in a planned Message Queue 3 2005Q1 installation:
./mqmigrate -basedir /export
The following command will migrate data from a Message Queue 3.5 instance to Message Queue 3 2005Q1 locations in a planned Message Queue 3 2005Q1 installation:
./mqmigrate
Finding and Removing Installed Message Queue RPMs (Versions 3.0.1 SP1 - 3.5 SP2)
To Find and Remove Earlier RPM-Installed Versions of Message Queue
- Enter the following command:
rpm -qa | grep mq
If found, the version numbers of any RPMs are imbedded in the RPM name. If none are found, proceed to Finding and Removing a Message Queue Tar-Based Installation.
Table 3-4 shows the version number that corresponds with RPM names for each Message Queue release.
- If you find Message Queue RPMs of a version earlier than Message Queue 3 2005Q1, remove them as follows:
- If you wish to preserve existing broker instance data, run the mqmigrate utility (in the Message Queue 3 2005Q1 distribution) as described on (more...) .
The mqmigrate utility moves existing broker instance data (broker configuration files and persistent data) and security-related files, to new Message Queue 3 2005Q1 locations.
- Remove the existing Message Queue installed software. Issue the following command(s) in the following order:
To remove the Enterprise Edition, run both commands.
Finding and Removing a Message Queue Tar-Based Installation
To Find and Remove Earlier Tar-Based Installed Message Queue
- See if the default Message Queue installation directory (/opt/imq/bin) exists on your system.
If found, proceed to Step 2.
If not found, Message Queue might have been installed in a non-default location. If you cannot remember the installation directory, search for the Message Queue imqbrokerd executable and note its root install directory. Proceed to Step 2.
If there is no previous Message Queue installation, proceed to install Message Queue by following the directions in Installing Message Queue on Linux.
- If you find an earlier Message Queue installation in the default location (/opt/imq/bin), remove it as follows:
- If you wish to preserve existing broker instance data, run the mqmigrate utility (in the Message Queue 3 2005Q1 distribution) as described on (more...) .
The mqmigrate utility moves existing broker instance data (broker configuration files and persistent data) and security-related files, to new Message Queue 3 2005Q1 locations.
- Remove the /opt/imq/ directory and all its contents.
rm -rf /opt/imq
Installed Directory Structure
The install image below reflects a full (all RPMs) Linux installation. This image might vary if you perform a partial installation.
Note
File locations for Message Queue bundled with Sun Java System Application Server, may differ from locations specified in Table 3-5.
Installing Message Queue on Linux
The following instructions explain how to download and install the Message Queue product on Linux from the Sun Java System website.
To Install Message Queue on Linux
- Accept the license agreement on the Message Queue product download site.
- Download the Message Queue product distribution file from the website into an empty, temporary download directory, temp_directory.
The download file is: mq3_6-plt-linx86.zip
- Change to the temp_directory and uncompress the distribution file.
unzip mq3_6-plt-linx86.zip
The unzip command creates a mq3_6-plt directory, which contains the distribution files: LICENSE, README, THIRDPARTYLICENSEREADME, and COPYRIGHT files; mqinstall utility; mquninstall utility; mqmigrate utility; and an rpms directory.
Table 3-6 describes the Message Queue RPM packages in the rpms directory. If any of these files already exist on your system, you need to check whether the version number is greater than that provided by Message Queue. If it is, you should do a custom install.
Table 3-6 RPM Packages in Linux Bundle
RPM
Description
Notes
sun-mq-config
/etc files
sun-mq-var
/var files
sun-mq
/opt files for the Platform Edition
Depends on sun-javahelp, sun-mq-jmsclient, sun-mq-config, and sun-mq-var
sun-mq-jaxm
Message Queue Java API for XML Messaging (JAXM): API
Depends on sun-saaj
sun-mq-jmsclient
JMS: API and runtime
No dependencies
sun-mq-xmlclient
XML Client
Depends on sun-jmsclient and sun-saaj
sun-mq-capi
C-API
Depends on sun-nspr, sun-nss
sun-mq-compat
Symlinks to 3.5 locations.
Depends on sun-mq.
Not installed by default. Use if your existing client applications contain scripts that depend upon former file locations (such as jar files).
sun-mq-sup
Needed to support client development and deployment on JDK 1.3
Depends on sun-mq
Not installed by default.
sun-mq-[locale]
L10N files
No dependencies
sun-javahelp1
JavaHelp: API and runtime
Supports JavaHelp viewer for Admin Console help
sun-nss1
Network Security Services (NSS) libraries.
Needed to support C language clients
sun-nspr1
Netscape Portable Runtime (NSPR) libraries
Needed to support C clients
sun-saaj1
SOAP with Attachments API for Java: API and runtime
Required to support Java clients using SOAP/JAXM API
sun-jaxp1
Message Queue Java API for XML Processing (JAXP): API and runtime
Required to support Java clients using SOAP/JAXM API
sun-javamail1
JavaMail: API and runtime
Required to support Java clients using SOAP/JAXM API
sun-jaf1
JavaBeans Activation Framework: API and runtime
Required to support Java clients using SOAP/JAXM API
1This RPM package is shared by a number of Sun Java System products
- Change to the directory containing the Message Queue distribution files.
cd mq3_6-plt
- Log in as root or change to superuser.
For example, type the following at a command prompt:
su root
When prompted, type your root password.
- If you intend to install all of the RPM packages listed in Table 3-6, you will need to run the mqinstall script. Please note that the install script will overwrite all the listed RPM packages.
- Run the mqinstall script.
./mqinstall
The script lists the distribution RPM packages including their version numbers, if any, that are already installed, and then lists the RPM packages about to be installed.
Note
If any of the Message Queue RPM packages listed are already installed and its version is newer, then you will probably not want to install the corresponding Message Queue RPM packages. In that case, enter n (no) and continue with Step 7.
The mqinstall script does not install the sun-mq-compat and sun-mq-sup RPM packages by default. For example, if your existing client applications contain scripts that depend upon former file locations (such as jar files), you will need to install the sun-mq-compat RPM package. If you are doing client development using JDK 1.3, you will need to install the sun-mq-sup RPM package. To install either or both of these RPM packages, see Step 7.
- Enter y (yes) if you want to install all the RPM packages, and skip to Step 8. Otherwise, enter n (no) and continue with Step 7.
If you run the script, it creates a log file in the following directory:
/var/sadam/install/logs
The /opt/sun/mq directory and its contents are created, and files are placed in other locations as well (see Migration Issues).
- If you do not want to install all of the RPM packages listed in Table 3-6 (you want only a subset, or you do not want to over-write later versions of RPM packages), do the following:
- Back up the imq3_6-plt-linx86.zip 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.
- Clean up all remaining files in your temporary working directory.
Configuring the Java Runtime for Message QueueAt startup time, a broker (the Message Queue message server) 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 both are passed in, 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/JRE. The broker will pick up the latest version JDK/JRE installed on the system (greater than 1.4 and less than 2.0).
The broker attempts to locate the JDK/JRE in the following order:
To find out why a broker is picking up a specific JDK/JRE, you can start the broker with the following command:
imqbrokerd -verbose
Locating Message Queue RPM InformationYou can query the RPM database to determine the installed version of RPMs, as well as the installed edition of Message Queue.
To query the description tag from an installed RPM
To query the installed Message Queue edition
- Use the following commands:
- for the Enterprise Edition
rpm -qa sun-mq-ent
This output shows version information for the Enterprise Edition RPM.
sun-mq-ent-3.6-n
- for the Platform Edition
rpm -qa sun-mq
This output shows version information for the Platform Edition RPMs, but does not list the sun-mq-ent (Enterprise Edition) RPM.
sun-mq-3.6-n
sun-mq-var-3.6-n
sun-mq-config-3.6-n
sun-mq-jaxm-3.6-n
...
Where To Go NextRead the README and Message Queue Release Notes files.
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 /opt/sun/mq/javadoc directory.
To uninstall the product, see the following section.
Uninstalling Message Queue on LinuxThe following instructions explain how to uninstall Message Queue on Linux.
To Remove Message Queue on Linux
- Stop any running client applications.
- Stop any running brokers. (You will be prompted for the admin user name and password.
imqcmd shutdown bkr [-b hostName:port]
- Unless you want to retain dynamic data, the Message Queue flat file user repository, and the Message Queue access control file associated with each broker instance, remove this data using the following command.
imqbrokerd -name instanceName -remove instance
- Get the uninstall script by following Step 5 through Step 7. If you already have the uninstall script you can proceed to Step 8.
- Find the zipped distribution file used to install Message Queue (see Step 2) and place it in a temporary directory, temp_directory.
- Change directories to temp_directory.
cd temp_directory
- Unzip the distribution file.
unzip mq3_6-plt-linx86.zip
- Change to the directory containing the Message Queue packages.
cd mq3_6-plt
- Become root:
su root
When prompted, type your root password.
- Run the uninstall script.
./mquninstall
The installation script lists the Message Queue RPM packages that are not shared, if any, that are currently installed. (It does not list shared Message Queue RPM packages installed with Message Queue, and which might be in use by other programs.)
- If you want to uninstall all the listed RPM packages, enter y (yes) and skip to Step 14. Otherwise, continue with Step 12.
- If you do not want to uninstall all of the Message Queue RPM packages, then enter n (no), and use the rpm -e command, as described in Step 13, to uninstall the specific RPM packages you want to remove.
- Remove the Message Queue RPM packages manually using the following command:
rpm -e packageName
where packageName is any of the Message Queue RPM packages. To remove multiple RPM packages, separate the package names by a space.
Because other products might be using Message Queue RPM packages, be careful about removing them.
- Exit the shell.