Configure the WebSphere MQ agent
This task describes how to configure the WebSphere MQ agent.
The WebSphere MQ Agent instance represents connection to a single WebSphere MQ Queue Manager. A virtual service can use multiple agent instances if it needs to access queues on multiple queue managers.
Configure the agent settings
From the main menu, select Tools > Options. On the Agents Page, select WebSphere MQ. For user interface details, see the WebSphere MQ agent settings.
MQ channel SSL configuration has the following main parts:
MQ server certificate: A certificate bound to a channel. It may be self-signed or signed by any certificate authority.
CipherSpec: Defines details of transport encryption and security level by specifying a predefined CipherSpec (SSL Cipher Suite) identifier. For more details, see “Enabling CipherSpecs” in the IBM MQ documentation.
SSL Authentication: Optional mutual SSL authentication by client certificate.
MQ server certificate
Service Virtualization needs to trust the certificate used by the MQ Channel to connect. The Root CA certificate of a certificate used by the MQ server must be in the
Trusted Root Certificate Authorities certificate store of
Current User or
Local Machine. Alternatively, this certificate store must contain an MQ server certificate if it is self-signed. The root certificate can be imported to the mentioned certificate store manually, or you can set the certificate path to the MQ Channel Root CA File configuration property and Service Virtualization will import the certificate to the proper certificate store when the agent starts if it is not already there. Supported certificate formats for the MQ Channel Root CA File property are:
*.CER (binary), supported on Windows only
MQ Channel configuration enables you to specify an exact CipherSpec value that is required by all incoming connections. If a client connects to MQ Channel with an unexpected CipherSpec value, its connection is accepted but it is closed on the first request. The usual result is an MQRC_Q_MGR_NOT_AVAILABLE error.
Unfortunately, the .NET SSL protocol implementation used by the Service Virtualization WebSphere MQ agent does not allow exact specification of CipherSpec (Cipher Suite in Windows terminology). It uses the first Cipher Suite that matches the selected SSL protocol version. For details on how to view and modify the System Cipher Suite order, see “Configuring TLS Cipher Suite Order” in the Windows documentation.
WebSphere MQ 9.1.1 introduced ANY_TLS12 CipherSpec and version 9.1.4 added ANY_TLS12_OR_HIGHER CipherSpec which accept all connections using TLS 1.2 protocol. These CipherSpec values are the most suitable for the Service Virtualization agent.
If you encounter an MQRC_Q_MGR_NOT_AVAILABLE error caused by a CipherSpec mismatch, below are possible solutions:
Make sure the proper SSL version is set in the SV MQ agent configuration according to the required CipherSpec.
If possible, modify the SSL configuration of the MQ Channel (or add a new channel to the queue manager) to use ANY_TLS12 or ANY_TLS12_OR_HIGHER CipherSpecs.
Modify the system Cipher Suite order on any machine running Service Virtualization. Remove all Cipher Suites related to the SSL protocol version (for example, TLS 1.2) before the Cipher Suite required by MQ Channel. This alternative has the following possible drawbacks:
It might affect other applications running on the machine.
It requires a system reboot to apply changes.
It is applicable on Windows only.
You can specify a client certificate for authentication even though the WebSphere MQ agent configuration does not allow you to set it. The MQ agent implementation searches Personal certificate store of Current User or Local Machine for a certificate having Friendly Name
%USERNAME% stands for name of a user running Service Virtualization. For example, it will be
ibmwebspheremqsvuser for user “svuser” or
ibmwebspheremqsystem for an SV server running as Windows service under a Local System account.
Debugging the connection to a WebSphere MQ server
We recommend verifying the connection properties used by IBM MQ Explorer and then configuring Service Virtualization with corresponding values in case of persisting connection problems.
Additional error details can be found in the MQ server error logs. They are usually located in the qmgrs/%QM_NAME%/errors folder on the MQ server machine.
The WebSphere MQ agent uses the IBM WebSphere MQ .NET Managed client internally. This enables you to use all diagnostic tools and logs provided by the client if you need to investigate any issues with WebSphere MQ communication between Service Virtualization and the IBM WebSphere MQ server.
Logging of MQ .NET Managed client can be enabled by setting these two environment variables and restarting Service Virtualization.
MQTRACEPATH=%APPDATA%\Micro Focus\Service Virtualization Designer\logs\
It produces files with names like
AMQ*.TRC in a folder specified by the
MQTRACEPATH value. Since the size of created trace files can grow rapidly, we recommend enabling this logging for debugging purposes only.
Troubleshooting WebSphere MQ server errors
Below is a list of common errors and possible solutions.
|Missing or invalid username or password.|
|MQRC_UNEXPECTED_ERROR (2195)||Invalid CCSID property value. Try to leave the CCSID value empty or set it to the exact value specified in the MQ Queue Manager configuration.|