Configuring an IBM MQ queue manager

How to configure a local IBM® MQ queue manager to enable communication between a DataPower® service and remote queue managers.

A local IBM MQ queue manager provides messaging services in the following ways.

Monitor and poll queues periodically.
Make sure that sent messages are directed to the correct receive queue or are routed to another queue manager.

Before you begin

Before you configure a local queue manager, determine whether to support secure connections with the remote queue manager.

For secure connections with a static URL, you can use a TLS client profile or TLS artifacts that were created with IBM Global Security Kit (GSKit). If you define both methods, the TLS client profile is used. To integrate with IBM MQ for z/OS®, you must use a TLS client profile.
Attention: IBM MQ mandates a specific TLS configuration to secure connections between client and server, where the connection uses the first cipher suite in the TLS client profile. When the TLS client profile includes multiple cipher suites, either delete all unneeded cipher suites or move the single supported cipher suite as the first one.
Do not use the same TLS client profile for IBM MQ and other protocols. When you configure the TLS client profile, make sure that the certificate validation mode for the referenced validation credentials is for full certificate chain checking (PKIX).

For more information, see the IBM MQ documentation.
For secure connections with a dynamic URL, see How to configure DataPower dynamic MQ URL to use MQ SSL channel.

About this task

The IBM MQ queue manager and IBM MQ v9+ queue manager objects provide almost all the same properties, and the queue managers are different DataPower objects. The following table highlights the differences between these objects.

Table 1. Differentiating property differences between queue manager objects
Property	IBM MQ queue manager	IBM MQ v9+ queue manager	Details
Username	Available	Unavailable	Specify a plain text string that identifies this client to the server. For GSKit artifacts that secure connections, the value identifies the certificate in the key database file.
FFST file size	Unavailable	Available	Specify the maximum size of the first-failure support technology (FFST) file in KB.
Number of FFST file rotations	Unavailable	Available	Specify the maximum number of FFST file rotations.
Error log size	Unavailable	Available	Specify the maximum size of the error log in bytes.
Error log rotations	Unavailable	Available	Specify the maximum number of error log rotations.
Compatibility mode	Unavailable	Available	Specify the compatibility mode for requests.
Units-of-work	Available	Available	Specify the syncpoint. IBM MQ queue manager supports a value in the range 0 - 65535 with a default value of 0. IBM MQ v9+ queue manager supports a value in the range 0 - 1 with a default value of 0.
Sharing conversations	Available	Available	Specify the maximum number of conversations that can share a TCP/IP connection. IBM MQ queue manager supports a value in the range 0 - 5000 with a default value of 0. IBM MQ v9+ queue manager supports a value in the range 1 - 5000 with a default value of 1.
Share single conversation	Available	Unavailable	Specify whether to share conversations when the number of shared conversations is 1.
Permit SSL v3	Available	Unavailable	Specify whether to enable the use of an SSL v3 cipher when GSKit artifacts secure connections.
TLS cipher specification	Available	Available	Specify the available cipher suite to support secure operations. The different local queue manager objects support different cipher suites.
TLS certificate label	Unavailable	Available	Specify the unique identifier of a digital certificate in the key database file when GSKit artifacts secure connections.
Outbound SNI	Unavailable	Available	Specify the SNI value to set to establish a secure connection to the remote server.
Check OCSP extensions	Unavailable	Available	Specify whether the TLS channel attempts an OCSP security check against the servers in the AIA certificate extension.
OCSP authentication	Unavailable	Available	Specify the action to take when the revocation status of a certificate cannot be determined from an OCSP server.
Check CDP extensions	Unavailable	Available	Specify whether the TLS channel attempts a CDP revocation check against the servers in the CDP certificate extension.
Client revocation checking	Unavailable	Available	Specify the behavior to check for revoked certificates against the CCDT file for clients that connect on the TLS channel.

Connections to dynamic queue managers

Connections to dynamic queue managers are kept alive until its connection information is removed from the DataPower connection cache. When you configure a local queue manager, set the Cache timeout property to define the duration in seconds to retain (keep alive) a dynamic connection in the connection cache. This property is the only way to configure a timeout value from the DataPower service to the server. No other DataPower setting can time out an IBM MQ connection.

The timeout value must be greater than the negotiated heartbeat interval but less than the keep alive interval.

The negotiated heartbeat interval is between the DataPower service and the IBM MQ server. This interval uses the value of the Channel heartbeat property to define the starting value for the negotiation.
The keep alive (timeout) interval is on the server. The KAINT attribute on the server defines the timeout value for a channel.
Not all channels have an explicit keep alive interval on the server. Some queue managers use an automatic timeout setting (the KAINT attribute set to AUTO). In these cases, the keep alive interval is the negotiated heartbeat interval plus 60 seconds.

When an inactive connection reaches this threshold, the dynamic connection is removed from the cache. When the cache no longer contains the dynamic connection, the dynamic queue manager is deleted. Without a dynamic queue manager, no connection is established with the server.

Procedure

In the search field, enter mq manager.
From the search results, click IBM MQ queue manager or IBM MQ v9+ queue manager.
Click Add.
Define the general configuration.
1. Define the basic properties: Name, administrative state, and descriptive summary.
2. In the Host field, specify the hostname or IP address and port of the server.
  The host for a queue manager is the IBM MQ server where the queue manager is running. The defined hostname includes the listening port on the server. If you do not specify the port, the default value is 1414. The value of the host depends on the IP family. The following examples all illustrate the same host-address configuration.
```
10.10.1.2:1414
10.10.1.2(1414)
10.10.1.2
[2202::148:248]:1414
2202::148:248(1414)
2202::148:248
server1:1414
server1(1414)
server1
```
3. Optional: In the Queue manager name field, specify the name of the queue manager. Use when the name of a nondefault queue manager is assigned to this queue manager.
4. Optional: In the Channel name field, specify the name of the channel. Use as an alternative to the default SYSTEM.DEF.SVRCONN.
5. In the Channel heartbeat field, specify the approximate time between heartbeat flows on a channel that is awaiting a message on a queue. If 0, no heartbeat flow is exchanged that is awaiting a message on the channel. This setting does not set the heartbeat on the channel. This setting negotiates the heartbeat value with the channel. Of the two values, the greater value is used.
6. Optional: IBM MQ queue manager only - In the Username field, specify a plain text string that identifies this client to the server. When GSKit artifacts secure connections, identify the certificate in the key database file.
7. Set Alternate user to determine whether to use MQOD.AlternateUserId or MQMD.UserIdentifier during MQOPEN and MQPUT operations.
8. From the XML manager list, select an XML manager.
9. Optional: In the Max message size field, specify the size in bytes of the largest message to process. Use a value that is equal to or greater than the MaxMsgLength attribute of the channel and of the queue on the server.
10. In the Cache timeout field, specify the number of seconds to retain a dynamic connection in the connection cache. Use a value that is greater than the negotiated heartbeat interval but less than the keep alive interval.
Optional: IBM MQ v9+ queue manager only - Define the maximum space in KB that the queue manager can use for FFST files.
FFST and FFDC (first-failure data capture) provide information about events that can help IBM Support personnel diagnose problems.
- FFST provides information about events. FFST files have the FDC file type.
- FFDC provides an automated snapshot of the system environment when an internal event occurs. When an error, the snapshot provides IBM Support personnel with a better understanding of the state of the system and IBM MQ when the problem occurred.
1. In the FFST file size field, specify the maximum size in KB of the FFST file. Enter a value in the range 100 - 50000. The default value is 500.
2. In the Number of FFST file rotations field, specify the maximum number of FFST file rotations. Enter a value in the range 3 - 5. The default value is 3.
Optional: IBM MQ v9+ queue manager only - Define the maximum space in bytes that the queue manager can use for error logs.
1. In the Error log size field, specify the maximum size in bytes of the error log. Enter a value in the range 32768 - 2147483648. The default value is 33554432.
2. In the Error log rotations field, specify the maximum number of error log rotations. Enter a value in the range 3 - 5. The default value is 3.
Optional: IBM MQ v9+ queue manager only - In the Compatibility mode field, specify the compatibility mode for requests to the queue manager, where the minimum required structure version is used. This setting is for message validation. By default, validation is against the version 3 structure.
Determine whether to support transactions (units-of-work).
A unit-of work can consist of one or more messages. Some IBM MQ systems require synchronization on each unit-of work. In other words, the system commits or rolls back the entire transaction. Synchronization makes sure that the remote system and the application with which it interacts remain in sync. DataPower processing supports only local units-of-work with the remote queue manager.
1. Set the Units-of-work property to 1 to indicate that the queue manager uses sync points.
  A sync point commits or rolls back each message, not the entire transaction. When specified, the retrieved message is not removed the message from the queue until it completes its transaction. If the transaction fails and the message remains on the queue, the DataPower service can attempt to get the message and process it again.
  When not enabled, undeliverable messages are discarded. Higher-level protocols are responsible for detecting and for retransmitting any undeliverable message within the transaction.
2. Enable the Automatic backout property to back out of poison messages automatically.
  A poison message is any message that the receiving application does not know how to process. Usually an application rolls back this message, which leaves the message on the input queue but increases the MQMD.Backoutcount backout count. As the local queue manager continues to attempt to retrieve the message, the backout count continues to increase. When the backout count reaches the backout threshold, the local queue manager moves the message to the backout queue.
  When not enabled, the request rule must use a custom stylesheet to reroute poison messages.
3. In the Backout threshold field, enter the number of total attempts to allow before moving the message to the backout queue and committing the unit-of work.
4. In the Backout queue name field, enter the name of the backout queue.
  The backout queue contains messages that cannot be processed or delivered, which is typically the SYSTEM.DEAD.LETTER.QUEUE queue name. Messages that exceed the backout threshold are rerouted to this queue.
Optional: Define open connection behavior.
1. In the Total connection limit field, specify the total number of open TCP connections to allow.
2. In the Initial connections field, specify the number of TCP connections to open immediately when the queue manager starts.
3. In the Local address field, specify the local address for outbound connections.
  Supported formats are 1.1.1.1 or 1.1.1.1(1) or (1) to tell TCP to bind to port 1 and for a range of ports use (1,10) or 1.1.1.1(1,10). If the port is set, the range must be greater than the total number of allowed connections.
Define the connection behavior to handle repeated connection failures.
1. Enable Automatic retry.
2. In the Retry interval field, specify the number of seconds between automatic connection attempts. This setting does not affect attempts to PUT or GET messages over established, active connections.
3. In the Retry attempts field, specify the number of attempts to try the failed connection again. After the reaching this number of attempts, use the long interval. If the long interval is not enabled, the queue manager repeatedly attempts to reconnect with the basic interval setting.
4. In the Long retry interval field, specify the number of seconds between attempting the failed connections after the number of connection attempts is reached. The long interval value must be greater than the value of the short interval. To disable, change the value in the Retry attempts field to 0.
5. In the Reporting interval field, specify the number of seconds between the creation of error messages when failed connections are tried again. This setting filters the generation of identical error messages to a log target.
Optional: Define whether conversations can share a single TCP/IP connection.
1. In the Sharing conversations field, specify the maximum number of conversations that can share a TCP/IP connection.
  The negotiated value with the server is the actual value for shared conversations.
2. Optional: IBM MQ queue manager only - Set Share single conversation to indicate whether to enable conversation sharing when the number of shared conversations is 1.
Determine whether to support secure connections with the remote queue manager.
TLS client profile
1. From the TLS client profile list, select the TLS client profile.
2. From the Outbound SNI list, select specifies where to retrieve the SNI value for SNI capable clients. By default, sets the value of the SNI header to the channel name. When set to use the hostname, per-channel certificates cannot be used.
Artifacts from GSKit
1. With the TLS key repository controls, select the location of the key database file.
  The key database file contains the needed keys and certificates. Each key database file has an associated stash file. The stash file holds encrypted passwords that allow programmatic access to the key database. The stash file must be in the same directory as the key database file, must have the same file stem, and must end with the sth file extension. If the key database file is MQkeys.pem or MQkeys.kdb, the stash file must be MQkeys.sth.
2. IBM MQ queue manager only - Set Permit SSL v3 to indicate whether to enable the use of an SSL v3 cipher.
3. From the TLS cipher specification list, select the cipher suite.
4. IBM MQ v9+ queue manager only - In the TLS certificate label field, specify the unique identifier of a digital certificate in the key repository.

Optional: IBM MQ v9+ queue manager only - Manage OCSP and CRL checking for TLS connectivity.

Table 2. OCSP and CRL properties
Property	Description
Check OCSP extensions	Specify whether the TLS channel attempts an OCSP security check against the servers in the AuthorityInfoAccess (AIA) certificate extension. This extension contains the server to contact through OCSP. When enabled, attempt an OCSP security check. This setting is the default value. When not enabled, do not run an OCSP security check.
OCSP authentication	Specify the action to take when the revocation status of a certificate cannot be determined from an OCSP server. REQUIRED Close the connection with an error. This setting is the default value. WARN Log a warning, but the connection continues as if no revocation check was made. OPTIONAL Continue the connection as if no revocation check was made.
Check CDP extensions	Specify whether the TLS channel attempts a CDP revocation check against the servers in the CrlDistributionPoint (CDP) certificate extension. This extension contains the URL that identifies the server to contact and the protocol to download the certificate revocation list (CRL). When enabled, attempt a CDP revocation check. When not enabled, do not run a CDP revocation check. This setting is the default value.
Client revocation checking	Specify the behavior to check for revoked certificates against the client channel definition table (CCDT) file for clients that connect on the TLS channel. REQUIRED Attempt to load the configuration for certificate revocation from the CCDT file, and run the check is run as configured. If the CCDT file cannot be opened or the certificate cannot be validated, the MQCONN call fails. A reason for failure is that the OCSP or CRL server is unreachable. When the CCDT file contains no revocation configuration, no check is run and the channel does not fail. This setting is the default value. OPTIONAL Attempt to load the configuration for certificate revocation from the CCDT file, and run the check as configured. If the CCDT file cannot be opened or the certificate cannot be validated, the MQCONN call does not fail. DISABLED No attempt to load the configuration for certificate revocation. No certificate revocation checking is done.

Optional: Define the CCSID to present to the remote queue manager.
1. In the Character code set ID field, specify the coded character set identifier (CCSID) to present to the queue manager during the connection.
  This setting has the same effect as setting the MQCCSID environment variable for the client.
2. Set Convert input to indicate whether the queue manager can convert input messages to a different CCSID than the one in the original message.
  This conversion is done by the remote queue manager. If error 2110 is encountered, disable this setting.
Optional: Define the MQCSP configuration.
The MQCSP support enables the authorization service to authenticate a user ID and password. You can specify the structure for the MQCSP connection security parameters on an MQCONNX call. For MQCSP support, you must define a security exit in the queue manager on the server.
1. In the MQCSP user ID field, specify the user ID value of the MQCSP connection security parameter.
2. From the MQCSP password alias list, select the password alias for the MQCSP connection security parameter.
Make sure that your MQCSP user ID and password in the security exit are consistent with the queue manager configuration. An inconsistent MQCSP user ID or an inconsistent password causes a connection failure.
1. If the MQCSP user ID or password is defined, the connection to the server is without MQCSP settings.
2. If only one is defined, a warning occurs. The queue manager configuration is not up.
3. If both are defined and one is inconsistent with its value on the server, the connection fails. The queue manager configuration is not up.
Click Apply to save changes to the running configuration.
Click Save to save changes to the persisted configuration.