WebSphere MQ for HP-UX, V5.3 GA 2 README

Content

WebSphere MQ for HP-UX, V5.3 README
Welcome to WebSphere MQ for HP-UX, Version 5.3.

This README file applies to WebSphere MQ books dated October 2002 and
CSD01 level of the V5.3 product shipped on or after October 2002.

This README file contains information that was not available in
time for our publications. In addition to this file, README.TXT,
you can find more information on the WebSphere MQ website:

http://www.ibm.com/support/entry/portal/Software/WebSphere/WebSphere_MQ

The SupportPac web page is here:

http://www.ibm.com/support/docview.wss?uid=swg27007205

For current information on known problems and available fixes, see
the Support page of the WebSphere MQ website here:

http://www.ibm.com/support/entry/portal/Software/WebSphere/WebSphere_MQ

Web documentation updates

The latest updates to the web-based WebSphere MQ documentation are now
available from the WebSphere MQ website here:

http://www.ibm.com/software/integration/wmq/library/library53.html


Note that latest changes are shown in red and earlier changes are shown in blue.

The Change History is located at the bottom of the page.



WebSphere MQ for HP-UX V5.3 Electronic Software Download installation
Introduction

These instructions apply to installing WebSphere MQ for HP-UX Version 5.3
from an installation image downloaded from IBM. Use it with the Quick
Beginnings manual for this release. A version of the Quick Beginnings book
is available from the download site; it has a description of 'WebSphere MQ
V5.3 Install Doc'. The installation image is provided as a compressed tape
archive (tar) file.

Installation Steps

1. Copy the WebSphere MQ tar file to a suitable directory accessible to the
machines where the software is to be installed. This directory must be on
a file system with at least 254Mb of free space (this is in addition to
the disk space required for the product, as detailed in the Quick
Beginnings publication).

2. Make this directory the current directory and use the command :

tar -xvf MQ53Server_hpux.tar

to create the installation image.

3. After this operation succeeds, you can delete MQ53Server_hpux.tar.

4. Use the WebSphere MQ for HP-UX V 5.3 Quick Beginnings manual to install
and configure the product. Replace any references to the CD drive by the
directory used in the steps above.

All other instructions remain the same.

WebSphere MQ for HP-UX V5.3 Quick Beginnings
Chapter 1, "Planning to install WebSphere MQ for HP-UX"
In the section "Prerequisite Software", in the operating system sub-section,
remove the two references to 32 bit.

WebSphere MQ for HP-UX runs on HP-UX version 11 and HP-UX version 11i
(11.11), running on either 32 bit or 64 bit hardware. It is not limited
to 32 bit versions of the operating system. However, the WebSphere MQ
processes and applications that connect to the WebSphere MQ processes
are only supported when running in 32 bit mode.

In the sub-section "SSL", replace sentence "SSL is not supported on HP-UX Version
11i." by:

"WebSphere MQ SSL runs successfully on HP-UX Version 11i when the following
patch bundles are applied:

HWEnable11i B.11.11.0112.5 Hardware Enablement Patches for HP-UX 11i,
December 2001
GOLDAPPS11i B.11.11.0112.6 Gold Applications Patches for HP-UX 11i,
December 2001 and
GOLDBASE11i B.11.11.0112.6 Gold Base Patches for HP-UX 11i,
December 2001".



WebSphere MQ V5.3 Intercommunication
Chapter 1, "Concepts of intercommunication"
In the section "Distributed queuing components", subsection "Channel
initiators and listeners", add the following subsection:

New channel behavior in WebSphere MQ

By default, in WebSphere MQ 5.3, threaded channels started by the channel
initiator or a listener do not run under that process, but under a process
called AMQRMPPA, otherwise known as a pool process.

To revert to the MQSeries 5.2 behavior, and have channels run under the
originating process, define an environment variable MQNOREMPOOL. The
existence of this variable, set to any value, runs the channel threads as
part of the listener or channel initiator process. This can be useful when
trying to isolate one or more channels from the rest of the configuration,
for example when testing channel exits.

Chapter 6, "Channel attributes"
In the section "Channel attributes in alphabetical order", subsection
"KeepAlive Interval (KAINT)", add the following:

You can set the KeepAlive Interval (KAINT) parameter for channels on a
per-channel basis. You can access and modify the parameter, but it
is only stored and forwarded on non-z/OS platforms; there is no functional
implementation of the parameter.

If you need the functionality provided by the KAINT parameter, use the
Heartbeat Interval (HBINT) parameter, as described in "Heartbeat interval
(HBINT)".


Chapter 47, "Channel-exit calls and data structures"
In the section "MQCD - Channel definition", add to the fields SSLPeerNamePtr
and SSLPeerNameLength the note:

When a certificate is received during a successful SSL handshake, the
Distinguished Name of the subject of the certificate is copied into the
MQCD field accessed by SSLPeerNamePtr at the end of the channel which
receives the certificate. It overwrites the SSLPeerName value for the channel
if this is present in the local user's channel definition.

If a security exit is specified at this end of the channel it will receive the
Distinguished Name from the peer certificate in the MQCD.


WebSphere MQ V5.3 SCRIPT (MQSC) Command Reference
SSL CipherSpecs TLS_RSA_WITH_AES_128_CBC_SHA and
TLS_RSA_WITH_AES_256_CBC_SHA are available for the HP-UX platform.

In the table "CipherSpecs that can be used with WebSphere MQ SSL support",
Note 7 should read "Available for AIX, HP-UX, and Linux Intel platforms
only".


Chapter 2, "The MQSC commands"
In the section "ALTER QMGR" add the following description of the GSK_PKCS11
value of the SSLCRYP parameter:

The PKCS #11 token label must be entirely in lower case. Note that if you have
configured your hardware with a mixed case or upper case token label you must
reconfigure it with this lower case label.





In the section "ALTER QMGR", parameter SSLCRLNL(nlname) description change the
list which describes when changes become effective to:

- On Windows and UNIX systems (apart from Linux for zSeries), when a new
outbound single channel process first runs an SSL channel.
- On Windows and UNIX systems (apart from Linux for zSeries), when a new
inbound TCP/IP single channel process first receives a request to start
an SSL channel.
- On Windows and UNIX systems (apart from Linux for zSeries), for channels
that run as threads of a process pooling process (amqrmppa), when the
process pooling process is started or restarted and first runs an SSL
channel. If the process pooling process has already run an SSL channel,
and you want the change to become effective immediately, restart the
queue manager.
- On Windows and UNIX systems (apart from Linux for zSeries), for channels
that run as threads of the channel initiator, when the channel initiator
is started or restarted and first runs an SSL channel. If the channel
initiator process has already run an SSL channel, and you want the change
to become effective immediately, restart the queue manager.
- On Windows and UNIX systems (apart from Linux for zSeries), for channels that
run as threads of a TCP/IP listener, when the listener is started or
restarted and first receives a request to start an SSL channel.
- On z/OS, when the channel initiator is restarted.

Add, after the list:

On OS/400 queue managers this parameter is ignored, however it is used to
determine what authentication information objects are written to the client
channel definition table.

On Linux for zSeries queue managers this parameter must not be specified when
channels are started, however it is used to determine what authentication
information objects are written to the client channel definition table. Note
that changes to SSLCRLNL, or to the names in a previously specified namelist,
or to previously referenced authentication information objects are reflected
immediately in the client channel definition table.



WebSphere MQ V5.3 Programmable Command Formats and Administration Interface
SSL CipherSpecs TLS_RSA_WITH_AES_128_CBC_SHA and
TLS_RSA_WITH_AES_256_CBC_SHA are available for the HP-UX platform.

In the table "CipherSpecs that can be used with WebSphere MQ SSL support",
Note 7 should read "Available for AIX, HP-UX, and Linux Intel platforms
only".


Chapter 3, "Definitions of Programmable Command Formats"
In the "Change Queue Manager" and "Inquire Queue Manager (Response)"
sections add the following description of the GSK_PKCS11 value of the
SSLCryptoHardware parameter:

The PKCS #11 token label must be entirely in lower case. Note that if you have
configured your hardware with a mixed case or upper case token label you must
reconfigure it with this lower case label.


WebSphere MQ V5.3 Using Java
Chapter 4, "Using WebSphere MQ classes for Java Message Service"
In the section "Running the sample applet", subsection "Running the
applet as an application", before running the applet using the command:

java JMSTestApplet

compile the applet using the command:

javac JMSTestApplet.java


Chapter 5, "Using the WebSphere MQ JMS administration tool"
In section "Administering JMS objects" add a note to Table 11 "Property names
and valid values":
In certain environments, specifying the same queue name for both the
brokerDurSubQueue and brokerCCDurSubQueue attributes on an MQTopic object can
result in a JMSException being thrown. It is advised that separate queues are
used for these two attributes."


Chapter 11, "Programming publish/subscribe applications"
In the section "Solving publish/subscribe problems" add a new section at
the end, as follows:

"Other Considerations"

When connecting to WebSphere MQ Event Broker V2.1 on a Microsoft Windows
system, with a large number of JMS clients using TCP/IP sockets (that
is with a JMSAdmin property type of TRANSPORT(DIRECT)), note the following.

If a large number of connections happen almost simultaneously, a
java.net.BindException Address in use exception might be thrown in response
to a TopicConnection call. You can try to avoid this by catching the
exception and retrying, or by pacing the connections.

WebSphere MQ V5.3 Security
Chapter 12, "Working with the Secure Sockets Layer (SSL) on UNIX systems"
The IKEYCMD command documented for creating a new CMS key database file does
not produce the password stash file, which is essential for successful SSL
message transfer.
To create a key database file and a password stash file use the following
IKEYCMD commands:

gsk6cmd -keydb -create -db <filename> -pw <password> -type cms -expire <days>
gsk6cmd -keydb -stashpw -db <filename> -pw <password>

where:

-db <filename> is the fully qualified path name of a CMS key database.
-pw <password> is the password for the CMS database.
-type cms is the type of database.
-expire <days> is the expiration time in days of the database password.
The default is 60 days for a database password.

In the section "Adding personal certificates to a key repository" before
step 1: "Execute the gsk6ikm command to start the iKeyman GUI." add a step
0.5: Ensure that the certificate file to be imported has write permission for
the current user


In the section "Configuring for cryptographic hardware" add a new last
paragraph (just above the section "Managing Certificates on PKCS #11
hardware"):

If you have configured cryptographic hardware which uses the PKCS #11 interface
using any of these methods, you must store the personal certificate for use on
your channels in the key database file for the cryptographic token you have
configured. This is described in "Managing Certificates on PKCS #11 hardware".

In the section "Managing Certificates on PKCS #11 hardware" replace point 8 by

8. Click OK. The Personal Certificates field shows the label of the new
personal certificate you added. You will note that this label is formed by
adding the cryptographic token label before the label you supplied.


WebSphere MQ V5.3 Application Programming Reference
Chapter 20, "MQSCO - SSL configuration options"

In the section "fields", in the CryptoHardware field, the GSK_PKCS11 string
should be described as
GSK_PKCS11= <the PKCS #11 driver path and filename>;
<the PKCS #11 token label>;<the PKCS #11 token password>;

Add the following description of this string

The PKCS #11 driver path is an absolute path to the shared library providing
support for the PKCS #11 card. The PKCS #11 driver filename is the name of the
shared library. An example of the value required for the PKCS #11 driver path
and filename is /usr/lib/pkcs11/PKCS11_API.so

The PKCS #11 token label must be entirely in lower case. Note that if you have
configured your hardware with a mixed case or upper case token label you must
reconfigure it with this lower case label.

WebSphere MQ V5.3 Application Programming Guide
Appendix A, "Language compilers and assemblers"
replace the existing
Table 59. Language compilers and assemblers for WebSphere MQ for HP-UX
by
---------------------------------------------------------
* Language * Compiler/Assembler *
*-----------+-------------------------------------------*
* C++ * aCC version A.03.27 or A.03.30 *
* * *
* C * IBM C for AIX, V5 or V6 *
* * IBM VisualAge C Professional, V5 or V6 *
* * *
* COBOL * Micro Focus Server Express, V2.0.10 or *
* * V2.0.11 *
---------------------------------------------------------



Information in various publications
In various books reference is made to strings containing RAINBOW which enable
or disable the Rainbow cryptographic hardware. Note that the hardware, if
present, is NOT enabled by default.

Strings containing NCIPHER enable or disable the nCipher cryptographic
hardware. Note that the hardware, if present, is NOT enabled by default.


Trademarks
The following terms are trademarks of the IBM Corporation in the
United States, or other countries, or both:

IBM MQSeries SupportPac WebSphere

ActiveX, Microsoft, Visual Basic, Visual C++, Windows, and Windows NT are
trademarks or registered trademarks of Microsoft Corporation in the United
States, other countries, or both.

Java™ and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States, other countries,
or both.

UNIX is a registered trademark of The Open Group in the United States
and other countries.

Other company, product, and service names may be trademarks or service marks
of others.

Change History 15th January 2003 Add information on use of SSLPeerNamePtr and SSLPeerNameLength in exits Add information to ALTER QMGR SSLCRLNL parameter changes