mqcertck (certify TLS setup)

Use the mqcertck command to diagnose potential TLS problems with your queue managers.

Purpose

The command can be used as a first check to determine why a connection using TLS has been unable to successfully connect to queue managers within your enterprise, and works with multiple certificates.

Syntax

Required parameters

QmgrName: Name of the queue manager to check for TLS errors.

Optional parameters

-clientkeyr client_key_repository

Required if you supply the -clientuser, -clientlabel, -clientchannel, or -clientport parameters.

Location of the client key repository used by a client application connecting to the referenced queue manager.

Important: You must supply the name without the .kdb extension.

-clientuser client_username

Cannot be used if you supplied the -clientlabel parameter.

User running the client application that connects to the referenced queue manager. If supplied, requires -clientkeyr.

-clientlabel client_certlabl

Cannot be used if you supplied the -clientuser parameter.

Certificate label that is given to the client that connects to the referenced queue manager by using one of the IBM® MQ MQI client CERTLABL methods. If supplied, requires -clientkeyr.

-clientchannel channel_name

Name of the channel on the referenced queue manager to check for TLS errors. If supplied, requires -clientkeyr.

-clientport port_number

Specify a specific port to use when testing the client.

The value must be:

An integer value between 1 and 65535 inclusive.
A port number, which must be a free port that mqcertck can use during its client checks.
Not be a port that is in use by the queue manager, or any other process on the machine running mqcertck.

If you do not specify a value, port 5857 is used. If supplied, requires -clientkeyr.

Examples

Example 1

After configuring an IBM MQ queue manager for TLS connections, you can use mqcertck to verify that no mistakes have been made, before attempting to start your channels.

The information returned in the example shows that no certificate has been found for queue manager qmgr.

[mqm@mq-host ~]$ mqcertck qmgr
5724-H72 (C) Copyright IBM Corp. 1994, 2025.
+----------------------------------------------------------
| IBM MQ TLS Configuration Test tool                       
+----------------------------------------------------------

ERROR:
No Certificate could be found for the Queue Manager qmgr

EXPLANATION:
Queue managers will use a certificate with the label set in the Queue Manager's
CERTLABL attribute. There is no certificate with the label ibmwebspheremqqmgr
in the key repository being used by the queue manager The Key repository being
used is located at /var/mqm/qmgrs/qmgr/ssl/key.kdb.

ACTION:
A valid certificate with the label ibmwebspheremqqmgr needs to be added to the
key repository.

+----------------------------------------------------------

This application has ended. See above for any problems found.

If there are problems then resolve these and run this tool again.

+----------------------------------------------------------

Example 2

After creating a key repository, certificate, and exchanging certificates for a client application, you can use mqcertck to verify that a client application is able to connect to a queue manager.

To do this, you need to run mqcertck on the machine where the IBM MQ queue manager is running, and have access to the client key repository.

You can do this in a variety of ways, for example, a file system mount. After you have set up your machine, run the following command:


mqcertck QmgrName -clientkeyr Location_of_Client_Key_Repository 
                     -clientlabel Client_certificate_label

For example:


mqcertck qmgr -clientkeyr  /var/mqm/qmgrs/qmgr/ssl/key
                     -clientlabel ibmwebspheremqqmgr

Check the output for any problems identified with your configuration.

Note that, if you are planning on having your clients connect anonymously, you can run the preceding command without the -clientlabel parameter.