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.

Back to top

SSL Configuration

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:

  • *.PEM (Base-64)

  • *.CER (binary), supported on Windows only

CipherSpec

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.

SSL Authentication

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 for a certificate having Friendly Name ibmwebspheremq%USERNAME%. Where %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.

Note: If SV Server runs under a special Local System user, it may be difficult to access its store of personal certificates in order to set a certificate there. It is possible to modify the Local System personal certificate store using certain methods, such as running the Microsoft Management Console using the PsExec Sysinternals tool in the context of the local system.

Running the SV Server under a dedicated admin user is simpler to configure and manage. For more details on reconfiguring the SV server to run under a dedicated admin user, see https://community.microfocus.com/adtd/sv/w/sv_tips/40139/how-to-run-sv-server-under-a-different-user.

Back to top

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.

MQ Client logging

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.

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

MQRC_HOST_NOT_AVAILABLE (2538)

  • Invalid host or port.

  • MQ server certificate is not trusted by Service Virtualization. Verify that the certificate in MQ Channel Root CA File is correct.

  • Service Virtualization for Linux (except Docker) may fail with this error on the first SSL used on a clean machine, regardless of the correct agent configuration. This might be caused by a missing the ~/.dotnet/corefx/cryptography/x509stores/my/ folder in the home directory of a user running the SV Server.

    Workaround: Create the missing folder with the same owner and permissions like existing ~/.dotnet/corefx/cryptography/x509stores/root/. If Service Virtualization was installed from RPM, then it is running as system service under sv-server user. Its home directory can be found in the /etc/passwd file.

MQRC_NOT_AUTHORIZED (2035)

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.
MQRC_Q_MGR_NOT_AVAILABLE (2059)

  • Connection is established, but it is immediately closed by the MQ server due to a CipherSpec mismatch. For details, see the MQ server error log mentioned above.

  • Mutual SSL authentication is required, but a client certificate is not specified or is invalid.

Back to top