WebSphere MQ Client, V5.3 README
Welcome to IBM WebSphere MQ Client
This README file applies to WebSphere MQ books dated October 2002 and CSD01 level of the V5.3 products shipped on or after October 2002.
This README file contains information you need to install IBM WebSphere MQ Client, as well as information that was not available for our printed publications.
Before you install IBM WebSphere MQ Client
- Information about installing
See the book WebSphere MQ Clients, GC34-6058, which is provided on the documentation CD1. Hardware and software requirements are described in this book in "Chapter2. Preparing for installation".
For instructions on installing the UNIX WebSphere MQ Clients from an installation image downloaded from IBM, see the section "Electronic Software Download installation" below.
- WebSphere MQ online documentation
The WebSphere MQ online documentation is available:
-In PDF format on the documentation CD1, in the /MSI//PDF directory.
- In compiled HTML format on the documentation CD1 in the /MSI//CHM directory. To view this, point your Web browser to the start.htm file in the CD-ROM file system.
- Getting help
See the section "Online information" in the WebSphere MQ Quick Beginnings book for your platform.
The WebSphere MQ website is here:
http://www.ibm.com/software/products/en/ibm-mq
The SupportPac™ page is here:
http://www.ibm.com/support/docview.wss?rs=977&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/docview.wss?rs=171&uid=swg27006037
- 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/
- Online version of this file
An online version of this readme file is maintained on the web, and might contain additions made since this file was frozen on this media. The site is here:
http://www.ibm.com/support/docview.wss?rs=171&uid=swg27006097
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.
Installing an IBM WebSphere MQ Client from Version 5.3 Products
A description of how to install an IBM WebSphere MQ client is in "Chapter 3. Installing client components from WebSphere MQ products and MQSeries Version 5 products (not z/OS)" in the WebSphere MQ Clients book, GC34-6058.
This readme file contains corrections and additions to that information, as shown below:
- Add the following new section:
Electronic Software Download installation
These instructions apply to installing the UNIX WebSphere MQ Clients from an installation image downloaded from IBM. Use it with the Quick Beginnings or Clients book 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 the amount of free space indicated
below (this is in addition to the disk space required for the product,
as detailed in the Quick Beginnings book):
MQ53Client_solaris.tar 120MB
MQ53ClientSSL_solaris.tar 200MB
MQ53Client_hpux.tar 70MB
MQ53ClientSSL_hpux.tar 190MB
MQ53Client_aix.tar 40MB
MQ53ClientSSL_aix.tar 110MB
MQ53Client_LinuxIntel.tar 250MB
MQ53ClientSSL_LinuxIntel.tar 310MB
MQ53Client_LinuxzSeries.tar 85MB
MQ53ClientSSL_LinuxzSeries.tar 140MB
The MQ53ClientSSL versions include the SSL channel support.
2. Make this directory the current directory and use the command:
tar -xvf .tar
to create the installation image.
3. After the operation succeeds, you can delete the .tar.
4. Use the WebSphere MQ Quick Beginnings book for your platform, or the
Clients book, 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.
In section "Installing on AIX" add:
The client CD contains two versions of the installation package, one with andcone without the support for Secure Sockets Layer (SSL) function. By default the installation procedure will use the full version. If you wish to install without support for SSL use this procedure.
- Insert the WebSphere MQ Clients CD-ROM 1 containing the AIX client into the CD-ROM drive.
- Mount the CD, for example:
> mount /cdrom1
- Specify the directory /cdrom1/aix/MQClient as the path input device or directory to smit or the -d argument to installp.
- Follow the procedure described in this chapter to install the client.
Other Amendments to the Clients Book Chapter 9, "The Secure Sockets Layer (SSL) on WebSphere MQ clients"
In section "Specifying the location of LDAP servers that hold certificate revocation lists (CRLs)" Just before the subsection "When a WebSphere MQ client application issues an MQCONNX call" add:
Note that you cannot access LDAP CRLs from a WebSphere MQ client channel running on Linux for zSeries.
WebSphere MQ for Linux for Intel and Linux for zSeries Quick Beginnings
Chapter 1, "Planning to install the WebSphere MQ for Linux products"
In section "Prerequisite software" under the "SSL" heading add:
If you want to use SSL channels on WebSphere MQ for Linux for Intel, you must install the following C++ runtime libraries:
libgcc_s.so
libstdc++.so.3
These libraries are installed with the GNU C++ compiler, version 3 and are available separately from your distribution vendor.
If you want to build C++ client applications that use SSL channels, you must use the GNU C++ compiler, version 3.
Section "Compiler runtime environment, Linux for Intel" describes the g++ version 3.0 compiler and its runtime libraries as a prerequisite if you want to use the SSL support with MQ. If your distribution does not come with this compiler or these libraries, this section describes how you can download the source for the compiler and build the required components. However, there are a few preparations you must make to ensure that, once complete, the new versions of these components are available for use by MQ:
By default the compiler is installed in the directory prefix of
/usr/local, so the compiler executables are installed into
/usr/local/bin and the runtime support libraries into /usr/local/lib.
If you build the compiler with this default, you might need to take some additional steps to ensure that the runtime support libraries can be found by MQ. You can do this by doing one of:
- Updating /etc/ld.so.config to include /usr/local/lib in the search path for libraries. (This may already be defined, depending on your distribution.)
- Copying and linking the runtime support libraries (libgcc_s.so and libstdc++.so.3) in /usr/local/lib to /usr/lib.
If you modify /etc/ld.so.config, you need to run the ldconfig command for the changes to take effect. Refer to the manual page for ldconfig for details.
Another option is to change the prefix used to build the compiler to /usr instead of /usr/local using the --prefix option on the configure command. However, doing this overwrites the executable files for the
previously installed compiler.
We recommend that you create backup copies of the compiler executable files. These are gcc and g++ for the C and C++ compilers, but there might be others if you are using the GNU Fortran or GNU Java™ Compilers.
Create the backup copies by copying them to gcc- and g++- respectively (replacing with the version number of the existing compiler). In this way you can compile programs with the previous version
of the compiler by using the compiler name suffixed with the version string. Using this method you can have multiple versions of the compiler installed.
Also, if you choose to build the compiler support rather than installing it from pre-built rpm files, the rpm database is not updated to reflect that these libraries have now been installed, so you might still get an
error that this dependency is missing when you try to install the gskit rpm file.
In this case install the gskit component using the additional option --nodeps, which does not perform the dependency checking while installing that rpm.
In section "Compiler runtime environment, Linux for zSeries"
Replace the text in this section with:
WebSphere MQ for Linux for zSeries is built using the GNU C and C++ compilers, version 2.95.3. If you want to use the C++ Bindings provided with WebSphere MQ then you must use this level of the compiler to build your C++ applications.
The SSL channels have a dependency on the C++ runtime provided with version 2.95.2 of the g++ compiler, called libstdc++-libc6.1.2.so.3 and normally found in /usr/lib. If you intend to run SSL channels you should ensure that this library is available on your system. If this is not available it can be obtained by installing the 'libstdc++' compat library provided by your distribution vendor.
WebSphere MQ for Solaris Quick Beginnings - V5.3
Chapter 1, "Planning to install WebSphere MQ for Solaris"
In the section "Prerequisite Software", in the operating system sub-section, remove the two references to 32 bit:
WebSphere MQ for Solaris runs on Solaris version 7 and Solaris version 8, 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.
WebSphere MQ for HP-UX Quick Beginnings - V5.3
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 section "SSL"
The sentence
"SSL is not supported on HP-UX Version 11i."
is replaced 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 for AIX V5.3 Quick Beginnings
Chapter 1, "Planning to install WebSphere MQ for AIX"
In the section "Prerequisite Software", in the operating system sub-section the statement, "The C/C++ runtime installed on AIX must be at level 5.0.2.0 or higher", should say "The C/C++ runtime installed on AIX must be at release 5.0.2.0 or at any later release of version 5".
Chapter 1, "Planning to install the WebSphere MQ for Windows Server"
Prerequisite server software
In section "Java" add
IBM 32-bit SDK for Windows, Java 2 Technology Edition, Version 1.4.0
Chapter 3, "Installing WebSphere MQ"
Add a note:
When installing on Windows XP using a Remote Desktop Connection, you will need to logoff, then re-logon to pick up the changes made to your environment by the installation process.
Installing on Windows 2000 using Terminal Services
It is possible to get errors when installing WebSphere MQ on this configuration. Microsoft KB article 255582 explains:
"When you are installing a Windows Installer-based setup program from a Windows 2000 Server Terminal Services session, you may receive one of the following error messages (where myapp.msi is the name of the .msi file that you are running).
On a system running the base version of Windows 2000, you will receive error
2755:
Internal Error 2755. 3 <Path>\myapp.msi.
On a system running Windows 2000 Service Pack 1, you will receive error 1305:
Error reading from file: <Path>\myapp.msi. Verify that the file exists and that you can access it.
CAUSE
These errors occur if you're running from a Terminal Server session and the path to the installation files is a mapped drive. The Windows Installer service is running in a different session than the user and therefore has different drive mappings. The errors occur because the .msi files that are needed cannot be found.
RESOLUTION
To work around this problem, use the full universal naming convention (UNC) path on the command line or run the installation from the Terminal Server console."
On WebSphere MQ the .msi file name is either "IBM WebSphere MQ.msi" or "IBM WebSphere MQ Extended Transactional Client.msi". The UNC is of the form "\\<ServerName>\<ShareName>\setup.exe" where <ServerName> and <ShareName> are the appropriate values for your machine setup.
Chapter 10: Using the WebSphere MQ Client CD-ROM
Add a section:
Installing the IBM 32-bit SDK for Windows, Java 2 Technology Edition, Version 1.4.0 from the client CD-ROM.
- Insert the WebSphere MQ Clients CD into the CD drive
- Click on Start menu - > Run
- Enter the drive letter of your CD ROM Drive for example E:\
- Open the "prereqs" folder
- Open the "JDK" folder
- Run the setup program "ibm-java2-sdk-140"
- Follow the on screen instructions to install the SDK for Java 2 v1.4.0
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 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 AIX, HP-UX, and Linux Intel platforms.
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", 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 AIX, HP-UX, and Linux Intel platforms.
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 4. Definitions of Programmable Command Formats
In the "Change Queue Manager" section, 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 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.
Chapter 13. Working with the Secure Sockets Layer (SSL) on Windows systems
In the section "Creating a self-signed personal certificate" add the following examples on using the makecert certificate creation tool.
Creating Test Certificates Using MakeCert
Note: these instructions were tested using Makecert.exe version
5.131.3617.0.
Creating and Installing a Certificate Authority Certificate
You should create a separate certificate for the a root certificate. This certificate will sign the SSL Certificate. The CA certificate in the example has an id named "WebSphereCA". You can name it whatever you like.
- makecert -pe -n CN=WebSphereCA -ss MY -sr CurrentUser -a sha1
-sky signature -r WebSphereCA.cer
- run or double click on TestCA.cer to install and trust the CA.
- On Dialog, click Install Certificate.
- Click the Next button.
- Click the "Place all certificates in the following Store" radio button and then click the Browse Button.
- Check the "show Physical Stores" checkbox.
- Expand the "Trusted Root Certification Authorities", select "Local Computer" and click the OK button.
- Click on the Next button and then the Finish button.
Creating the SSL Server Certificate
This example uses WebSphereMQ as the name of the SSL Certificate.
makecert -pe -n CN=WebSphereMQ -ss MY -sr CurrentUser -a sha1 -sky exchange
-eku 1.3.6.1.5.5.7.3.1 -in WebSphereCA -is MY -ir CurrentUser
-sp "Microsoft RSA SChannel Cryptographic Provider"
-sy 12 WebSphereMQ.cer
(Note: ensure the -sp name is exactly as specified in the example.)
Importing the SSL Certificates
The CA and Personal Certificates (issued to WebSphere in this example) can then be imported into the queue manager or client certificate stores using the WebSphere MQ Explorer, WebSphere MQ Services or amqmcert command line utility.
In the section "Requesting a personal certificate" add:
Strong Private Key Protection
When importing a certificate into the Personal Certificate store for the Current User, an option to "Enable strong private key protection" is offered. If this option is selected a dialogue is started where the level of security can be chosen. The dialogue offers a choice of High or Medium.
Both state that usage of this item will invoke a request for a user response. If either of these security levels are selected IBM WebSphere MQ will request a user response when the certificate is imported into the QM store. Any further user request will not then be made when WebSphere MQ "uses" this certificate: for example when channels are established.
Chapter 16, "Working with Certificate Revocation Lists"
In section "Accessing CRLs with a WebSphere MQ client" add at end:
You cannot access LDAP CRLs from a WebSphere MQ client channel running on Linux for zSeries.
Chapter 19, "Understanding authentication failures"
Add a new subsection:
SSL has encountered something it does not support. You may be attempting to access LDAP CRLs on Linux for zSeries. This is not possible.
Appendix A, "Cryptographic hardware"
Add a new entry to the list of supported cryptographic hardware:
IBM e-business Cryptographic Accelerator (#4960)
Interface: PKCS #11
Platforms:
AIX 5.1
Various places in the security manual reference the MQSSLCRYP environment variable stating that the permitted values for MQSSLCRYP are the same as for the SSLCRYP parameter. The PKCS #11 token label which can be used in the SSLCRYP (and therefore in the MQSSLCRYP environment variable) 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 Programmable Command Formats and Administration Interface
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.
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 TXSeries 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.
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
Last Updated: 7 October 2005
|