IBM® WebSphere® MQ (hereafter referred to as WebSphere MQ) queue manager clusters provide workload balancing and reduce the cost of system administration in WebSphere MQ networks by auto-defining channels between queue managers. It is possible to secure WebSphere MQ channels using Secure Sockets Layer (SSL), which provides encryption of data, authentication of partner, and detection of message tampering.
This article describes how to enable SSL in an existing WebSphere MQ queue manager cluster. You will create a new set of channels with SSL enabled, in addition to the pre-existing non-SSL channels. Once the SSL channels are working, you will remove the non-SSL channels. Although this method is more complex than simply altering pre-existing channels, it minimises the risk of application problems, caused by channel outages, during SSL enablement.
After you enable SSL, you will learn how you can use channel net priority (NETPRTY) to alter workload balancing behaviour during SSL enablement.
The article refers to several scripts in the Download section.
Overview: Enabling SSL in the cluster
The main tasks required to enable SSL in the cluster are:
- Administer certificates.
- Create the queue manager key repositories
- Create and distribute the CA certificate
- Create the queue manager certificates
- Set SSLKEYR on all queue managers
- Define the new SSL channels
- Define new cluster receivers with SSL on all the full repositories.
- Define new cluster senders with SSL on all the full repositories.
- Define new cluster receivers with SSL on all the partial repositories.
- Define new cluster senders with SSL on all the partial repositories.
- Verify that the SSL channels are working
- Delete the non-SSL channels
Setting up a queue manager cluster
We based the example cluster on the Windows machine setup in Table 1.
Table 1. Windows Machine setup
| Host | Use |
|---|---|
myhost1 | Hosts queue manager QM1 (Full repository) |
myhost2 | Hosts queue manager QM2 (Full repository) |
myhost3 | Hosts queue manager QM3 (Partial repository) |
myhost4 | Hosts queue manager QM4 (Partial repository) |
myhost5 | Security Administrator machine (The CA certificate is stored here and used to sign the queue manager certificates). |
Important: We defined cluster queues of the same name (QX) on all four queue managers, as this ensures that all queue managers auto-define cluster channels to one another. The tasks below require that all queue managers in the original cluster have healthy cluster channels to and from all other queue managers.
We actually ran the examples on one machine with myhost1-5 all resolving to localhost.
We used WebSphere MQ V6.0 and the certificate administration tool GSkit, which is incompatible with WebSphere MQ V5.3.
To see the commands used to create the cluster, refer to script create_qmgrs.bat in the Download section.
To see the output from DIS CHS and DIS CLUSQMGR for the pre-SSL cluster, refer to Appendix A
Before altering WebSphere MQ objects you need to set-up key repositories and certificates for all queue managers in the cluster. You can use an external Certification Authority (CA) outside the department or company, but this example uses an internal CA and so includes the steps required to sign certificate requests. You can also use self-signed certificates, but we donât recommend this method because of the associated high administration cost.
a. Create the queue manager key repositories
To create a key repository for each queue manager:
- Create QM1 key repository on myhost1:
runmqckm -keydb -create -db "C:\Program Files\IBM\WebSphere MQ\Qmgrs\QM1\ssl\qm1.kdb" -pw password -type cms -expire 365 -stashImportant: Using a password of âpasswordâ is not recommended. Passwords should be set according to your companyâs password standards.
- Create QM2 key repository on myhost2:
runmqckm -keydb -create -db "C:\Program Files\IBM\WebSphere MQ\Qmgrs\QM2\ssl\qm2.kdb" -pw password -type cms -expire 365 -stash - Create QM3 key repository on myhost3:
runmqckm -keydb -create -db "C:\Program Files\IBM\WebSphere MQ\Qmgrs\QM3\ssl\qm3.kdb" -pw password -type cms -expire 365 -stash - Create QM4 key repository on myhost4:
runmqckm -keydb -create -db "C:\Program Files\IBM\WebSphere MQ\Qmgrs\QM4\ssl\qm4.kdb" -pw password -type cms -expire 365 -stash - Create CA key repository on myhost5:
runmqckm -keydb -create -db "C:\mq\ssl\wmqca.kdb" -pw password -type cms -expire 365 -stash
b. Create and distribute the CA certificate
To create a CA certificate on the Security Administrator machine and distribute the public CA certificate to each WebSphere MQ machine:
- Create the CA certificate on myhost5:
runmqckm -cert -create -db "C:\mq\ssl\wmqca.kdb" -pw password -labelwmqca -dn " CN=WMQ CA, OU=WMQ, O=IBM, L=Hursley, ST=Hampshire, C=UK," -expire 365 - Check that the CA certificate is listed in the CA key repository on myhost5:
runmqckm -cert -list -db "C:\mq\ssl\wmqca.kdb" -pw password - Extract the public CA certificate on myhost5:
runmqckm -cert -extract -db"C:\mq\ssl\wmqca.kdb"-pw password -label wmqca -target wmqca.crt -format ascii - FTP the public CA certificate from myhost5 to myhost1.
FTP wmqca.crt in ASCII mode from myhost5 to myhost1. Name the file on myhost1
wmqca.crt - Add the public CA certificate to QM1âs key repository on myhost1:
runmqckm -cert -add -db "C:\Program Files\IBM\WebSphere MQ\Qmgrs\QM1\ssl\qm1.kdb" -pw password -label wmqca -file wmqca.crt -format ascii - Check that the public CA certificate is listed in QM1âs key repository on myhost1:
runmqckm -cert -list -db "C:\Program Files\IBM\WebSphere MQ\Qmgrs\QM1\ssl\qm1.kdb" -pw password - To distribute the public CA certificate to the other queue managers repeat steps 4 to 6 for QM2, QM3 and QM4 replacing the parameters in bold.
c. Create the queue manager certificates
To create the queue manager certificates:
- Create QM1âs certificate request on myhost1:
runmqckm -certreq -create -db "C:\Program Files\IBM\WebSphere MQ\Qmgrs\QM1\ssl\qm1.kdb" -pw password -label ibmwebspheremqqm1 -dn " CN=QM1, OU=WMQ, O=IBM, L=Hursley, ST=Hampshire, C=UK" -file qm1req.arm - FTP QM1âs certificate request from myhost1 to myhost5.
FTP qm1req.arm in ASCII mode from myhost1 to myhost5. Name the file on myhost5
qm1req.arm. - Sign QM1âs certificate on myhost5:
runmqckm -cert -sign -file qm1req.arm -db"C:\mq\ssl\wmqca.kdb" -pw password -label wmqca -target qm1cert.arm -format ascii -expire 364 - FTP QM1âs certificate from myhost5 to myhost1.
FTP qm1cert.arm in ASCII mode from myhost5 to myhost1. Name the file on
myhost1qm1cert.arm. - Add QM1âs certificate to QM1âs key repository on myhost1:
runmqckm -cert -receive -db "C:\Program Files\IBM\WebSphere MQ\Qmgrs\QM1\ssl\qm1.kdb" -pw password -file qm1cert.arm -format ascii - Check that QM1âs certificate is listed in QM1âs key repository on myhost1:
runmqckm -cert -list -db "C:\Program Files\IBM\WebSphere MQ\Qmgrs\QM1\ssl\qm1.kdb" -pw password - To create the other queue manager certificates repeat steps 1 to 6 for QM2, QM3 and QM4 replacing the parameters in bold.
Important: GSkit commands are case sensitive. Label names for queue manager certificates should be formatted as defined in the âWorking with WebSphere MQ SSL supportâ section of the WebSphere MQ Security manual (SC34-6588-01, see Resources).
2. Set SSLKEYR on all queue managers
To set each queue managerâs key repository:
- Set QM1âs queue manager key repository on myhost1:
ALTER QMGR SSLKEYR('C:\Program Files\IBM\WebSphere MQ\Qmgrs\QM1\ssl\qm1') - Set QM2âs queue manager key repository on myhost2:
ALTER QMGR SSLKEYR('C:\Program Files\IBM\WebSphere MQ\Qmgrs\QM2\ssl\qm2') - Set QM3âs queue manager key repository on myhost3:
ALTER QMGR SSLKEYR('C:\Program Files\IBM\WebSphere MQ\Qmgrs\QM3\ssl\qm3') - Set QM4âs queue manager key repository on myhost4:
ALTER QMGR SSLKEYR('C:\Program Files\IBM\WebSphere MQ\Qmgrs\QM4\ssl\qm4')
Important: Changes to SSLKEYR may not become effective immediately. For further information see the âALTER QMGRâ section of the WebSphere MQ Script (MQSC) Command Reference manual (SC34-6597-00).
To see the commands used to define each queue managerâs key repository, refer to script alter_qmgrs_sslkeyr.bat.
3. Define the new SSL channels
Next, define the new SSL channels.
Important: Define the channels in the correct order:
- Define new cluster receivers with SSL on all the full repositories.
- Define new cluster senders with SSL on all the full repositories.
- Define new cluster receivers with SSL on all the partial repositories.
- Define new cluster senders with SSL on all the partial repositories.
The channels should be defined in this order to avoid channel errors and configuration problems. If a different order is used (e.g. the different order used in script create_ssl_channels.bat, see the Download section) the new channels should still work, but are likely to go into retry and therefore take more time to successfully start.
Before defining new SSL channels
Before defining the new SSL channels, ensure that the existing channels work correctly, as the instructions assume that changes to cluster objects are published around the cluster via running channels. Each step contains instructions that describe how to check that cluster objects have been published correctly.
At this stage every queue manager should have a key repository populated with the certificates it needs to run SSL channels. This is a good time to ensure that SSL channels work correctly before you change the existing cluster channels. To test that the SSL certificate setup has been successful:
- Define a simple point-to-point non-cluster channel with SSL between two queue managers.
- Start the channel.
- Check that SSL is enabled on the channel, using
DIS CHL(. . .) SSLCIPH. A non-blank SSLCIPH indicates that SSL is enabled on the channel. - Send some messages over the channel.
- Check that SSL is running correctly, using
DIS CHS(. . .) SSLPEER. Both ends of the channel should show their partners Distinguished Name (DN) since both queue managers have a certificate.
a. Define the new cluster receivers with SSL on all full repositories
Next, define a cluster receiver channel with SSL on all full repositories. When you define the cluster receiver channels, the other queue managers in the cluster will auto-define cluster sender channels based on the definition of the new cluster receiver channels.
- Define a cluster receiver with SSL on full repository QM1 on myhost1:
DEFINE CHANNEL(TO.QM1.S) CHLTYPE(CLUSRCVR) CLUSTER(DEMO) TRPTYPE(TCP) CONNAME('myhost1(1414)') SSLCIPH(TRIPLE_DES_SHA_US)This command creates a new cluster queue manager object on QM1. The queue manager will publish the new cluster queue manager object out to other queue managers in the cluster over the existing non-SSL channels. The other queue managers will use the new definition to create auto-defined cluster channels to QM1. The next steps check that all objects have been created correctly.
- Check that you created the new cluster queue manager object locally on myhost1. There should now be two cluster queue manager objects for QM1 on QM1 (see Listing 1).
If the new SSL cluster queue manager does not display, check the result of the
DEFINE CHANNELin the previous step.
Listing 1. Output from DIS CLUSQMGR(QM1) STATUS SSLCIPHC:\>echo dis clusqmgr(QM1) status sslciph | runmqsc QM1 5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED. Starting MQSC for queue manager QM1. 1 : dis clusqmgr(QM1) status sslciph AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM1) CHANNEL(TO.QM1.S) CLUSTER(DEMO) SSLCIPH(TRIPLE_DES_SHA_US) STATUS(RUNNING) AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM1) CHANNEL(TO.QM1) CLUSTER(DEMO) SSLCIPH( ) STATUS(RUNNING) One MQSC command read. No commands have a syntax error. All valid MQSC commands were processed. - Check that the queue manager published the new cluster queue manager object correctly and that the other queue managers defined the auto-defined cluster sender channels correctly. You should now have two cluster queue manager objects for QM1 on:
- QM2 on myhost2
- QM3 on myhost3
- QM4 on myhost4
If the new SSL cluster queue manager object does not display, then QM1 didnât publish the cluster object correctly. Check the channel from QM1 to the problem queue manager to make sure it is working properly.
The new cluster queue manager object should have a channel status of either
INACTIVEorRUNNING(see Listing 2). If the status isRETRYING, check for error messages. It is likely theDEFINE CHANNELcommand on QM1 was incorrect. To fix this, simply alter the cluster receiver on QM1. There is no need to use REFRESH CLUSTER to fix a bad definition in this situation. Once the channel definition is fixed, start theRETRYINGchannel manually.
Listing 2. Output from DIS CLUSQMGR(QM1) STATUS SSLCIPHC:\>echo dis clusqmgr(QM1) status sslciph | runmqsc QM2 5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED. Starting MQSC for queue manager QM2. 1 : dis clusqmgr(QM1) status sslciph AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM1) CHANNEL(TO.QM1.S) CLUSTER(DEMO) SSLCIPH(TRIPLE_DES_SHA_US) STATUS(INACTIVE) AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM1) CHANNEL(TO.QM1) CLUSTER(DEMO) SSLCIPH( ) STATUS(RUNNING) One MQSC command read. No commands have a syntax error. All valid MQSC commands were processed. C:\>echo dis clusqmgr(QM1) status sslciph | runmqsc QM3 5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED. Starting MQSC for queue manager QM3. 1 : dis clusqmgr(QM1) status sslciph AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM1) CHANNEL(TO.QM1.S) CLUSTER(DEMO) SSLCIPH(TRIPLE_DES_SHA_US) STATUS(RUNNING) AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM1) CHANNEL(TO.QM1) CLUSTER(DEMO) SSLCIPH( ) STATUS(INACTIVE) One MQSC command read. No commands have a syntax error. All valid MQSC commands were processed. C:\>echo dis clusqmgr(QM1) status sslciph | runmqsc QM4 5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED. Starting MQSC for queue manager QM4. 1 : dis clusqmgr(QM1) status sslciph AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM1) CHANNEL(TO.QM1.S) CLUSTER(DEMO) SSLCIPH(TRIPLE_DES_SHA_US) STATUS(RUNNING) AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM1) CHANNEL(TO.QM1) CLUSTER(DEMO) SSLCIPH( ) STATUS(INACTIVE) One MQSC command read. No commands have a syntax error. All valid MQSC commands were processed. - To define new cluster receivers with SSL on the other full repository repeat steps 1 to 3 for QM2 replacing the parameters in bold.
To see the commands used to create the SSL channels, refer to script create_ssl_channels.bat in the Download section.
b. Define the new cluster senders with SSL on all full repositories
Next, define the cluster sender channels with SSL on all full repositories. Because the new channel definitions are cluster senders, the queue manager will not publish the definition to other queue managers in the cluster.
- Define a cluster sender with SSL on full repository QM1 on myhost1:
DEFINE CHANNEL(TO.QM2.S) CHLTYPE(CLUSSDR)CLUSTER(DEMO)TRPTYPE(TCP) CONNAME('myhost2(1415)') SSLCIPH(TRIPLE_DES_SHA_US)Important: A cluster queue manager object with SSL for QM2 already exists on QM1, so this command will not create a new cluster queue manager object. The object already existing is an auto-defined cluster sender based on the cluster receiver definition on QM2. Defining the new manual cluster sender channel on QM1 will alter the
DEFTYPEof the existing cluster queue manager object fromCLUSSDRAtoCLUSSDRB. - Check that the existing cluster queue manager object is now a
CLUSSDRB(see Listing 3). You should have two cluster queue manager objects for QM2 on QM1.If the SSL cluster queue manager is not a
CLUSSDRB, check the result of theDEFINE CHANNELin the previous step.
Listing 3. Output from DIS CLUSQMGR(QM2) STATUS SSLCIPH DEFTYPEC:\>echo dis clusqmgr(QM2) status sslciph deftype | runmqsc QM1 5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED. Starting MQSC for queue manager QM1. 1 : dis clusqmgr(QM2) status sslciph deftype AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM2) CHANNEL(TO.QM2.S) CLUSTER(DEMO) DEFTYPE(CLUSSDRB) SSLCIPH(TRIPLE_DES_SHA_US) STATUS(RUNNING) AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM2) CHANNEL(TO.QM2) CLUSTER(DEMO) DEFTYPE(CLUSSDRB) SSLCIPH( ) STATUS(RUNNING) One MQSC command read. No commands have a syntax error. All valid MQSC commands were processed. - To define new cluster sender with SSL on the other full repository repeat steps 1 and 2 for QM2 replacing the parameters in bold.
To see the commands used to create the SSL channels, refer to script create_ssl_channels.bat in the Download section.
c. Define the new cluster receivers with SSL on all partial repositories
Next, define the cluster receiver channels with SSL on all partial repositories. When you define the channels, other queue managers in the cluster should auto-define cluster senders. The auto-defined cluster sender channels base themselves on the definition of the new cluster receivers. The queue managers that will auto-define cluster sender channels are all the full repositories and partial repositories that subscribe to the queue manager on which the new cluster receiver channel is defined. In the cluster used in the examples every queue manager subscribes to every other queue manager.
- Define a cluster receiver with SSL on partial repository QM3 on myhost3:
DEFINE CHANNEL(TO.QM3.S) CHLTYPE(CLUSRCVR) CLUSTER(DEMO) TRPTYPE(TCP) CONNAME('myhost3(1416)') SSLCIPH(TRIPLE_DES_SHA_US)This command should create a new cluster queue manager object on QM3. The queue manager should publish the new cluster queue manager object out to other queue managers in the cluster over the other cluster channels. The other queue managers will use the new definition to create auto-defined cluster channels to QM3. The next steps check that all objects have been created correctly.
- Check that you created the new cluster queue manager object locally on myhost3. You should now have two cluster queue manager objects for QM3 on QM3 (see Listing 4).
If the new SSL cluster queue manager does not display, check the result of the
DEFINE CHANNELin the previous step.
Listing 4. Output from DIS CLUSQMGR(QM3) STATUS SSLCIPHC:\>echo dis clusqmgr(QM3) status sslciph | runmqsc QM3 5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED. Starting MQSC for queue manager QM3. 1 : dis clusqmgr(QM3) status sslciph AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM3) CHANNEL(TO.QM3.S) CLUSTER(DEMO) SSLCIPH(TRIPLE_DES_SHA_US) STATUS(INACTIVE) AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM3) CHANNEL(TO.QM3) CLUSTER(DEMO) SSLCIPH( ) STATUS(RUNNING) One MQSC command read. No commands have a syntax error. All valid MQSC commands were processed. - Check that the queue manager published the new cluster queue manager object correctly and that the other queue managers defined the auto-defined cluster sender channels correctly. You should now have two cluster queue manager objects for QM3 on:
- QM1 on myhost1
- QM2 on myhost2
- QM4 on myhost4
If the new SSL cluster queue manager object does not display, the cluster object from QM3 was not published correctly. Check the channel from QM3 to the problem queue manager to make sure it is working properly.
The new cluster queue manager object should have a channel status of either
INACTIVEorRUNNING(see Listing 5). If the status isRETRYING, check for error messages. It is likely theDEFINE CHANNELcommand on QM3 was incorrect. To fix this, simply alter the cluster receiver on QM3. You do not need to use REFRESH CLUSTER to fix a bad definition in this situation. Once you fix the channel definition, start theRETRYINGchannel manually.
Listing 5. Output from DIS CLUSQMGR(QM3) STATUS SSLCIPHC:\>echo dis clusqmgr(QM3) status sslciph | runmqsc QM1 5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED. Starting MQSC for queue manager QM1. 1 : dis clusqmgr(QM3) status sslciph AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM3) CHANNEL(TO.QM3.S) CLUSTER(DEMO) SSLCIPH(TRIPLE_DES_SHA_US) STATUS(INACTIVE) AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM3) CHANNEL(TO.QM3) CLUSTER(DEMO) SSLCIPH( ) STATUS(RUNNING) One MQSC command read. No commands have a syntax error. All valid MQSC commands were processed. C:\>echo dis clusqmgr(QM3) status sslciph | runmqsc QM2 5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED. Starting MQSC for queue manager QM2. 1 : dis clusqmgr(QM3) status sslciph AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM3) CHANNEL(TO.QM3.S) CLUSTER(DEMO) SSLCIPH(TRIPLE_DES_SHA_US) STATUS(INACTIVE) AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM3) CHANNEL(TO.QM3) CLUSTER(DEMO) SSLCIPH( ) STATUS(RUNNING) One MQSC command read. No commands have a syntax error. All valid MQSC commands were processed. C:\>echo dis clusqmgr(QM3) status sslciph | runmqsc QM4 5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED. Starting MQSC for queue manager QM4. 1 : dis clusqmgr(QM3) status sslciph AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM3) CHANNEL(TO.QM3.S) CLUSTER(DEMO) SSLCIPH(TRIPLE_DES_SHA_US) STATUS(INACTIVE) AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM3) CHANNEL(TO.QM3) CLUSTER(DEMO) SSLCIPH( ) STATUS(INACTIVE) One MQSC command read. No commands have a syntax error. All valid MQSC commands were processed. - To define new cluster receivers with SSL on the other partial repository repeat steps 1 to 3 for QM4 replacing the parameters in bold.
To see the commands used to create the SSL channels, refer to script create_ssl_channels.bat in the Download section.
d. Define the new cluster senders with SSL on all partial repositories
Next, define the cluster sender channels with SSL on all partial repositories. Manually defined cluster sender channels should be directed at full repositories. Because the new channel definition is a cluster sender, the queue manager will not publish the definition to other queue managers in the cluster.
- Define a cluster sender with SSL on partial repository QM3 on myhost3.
DEFINE CHANNEL(TO.QM1.S) CHLTYPE(CLUSSDR)CLUSTER(DEMO)TRPTYPE(TCP) CONNAME('myhost1(1414)') SSLCIPH(TRIPLE_DES_SHA_US)Important: A cluster queue manager object with SSL for QM1 already exists on QM3, so this command will not create a new cluster queue manager object. The object already existing is an auto-defined cluster sender based on the cluster receiver definition on QM1. Defining the new manual cluster sender channel on QM3 will alter the
DEFTYPEof the existing cluster queue manager object fromCLUSSDRAtoCLUSSDRB. - Check that the existing cluster queue manager object is now a
CLUSSDRB. You should have two cluster queue manager objects for QM1 on QM3 (see Listing 6).If the SSL cluster queue manager is not a
CLUSSDRB, check the result of theDEFINE CHANNELin the previous step.
Listing 6. Output from DIS CLUSQMGR(QM1) STATUS SSLCIPH DEFTYPEC:\>echo dis clusqmgr(QM1) status sslciph deftype | runmqsc QM3 5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED. Starting MQSC for queue manager QM3. 1 : dis clusqmgr(QM1) status sslciph deftype AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM1) CHANNEL(TO.QM1.S) CLUSTER(DEMO) DEFTYPE(CLUSSDRB) SSLCIPH(TRIPLE_DES_SHA_US) STATUS(RUNNING) AMQ8441: Display Cluster Queue Manager details. CLUSQMGR(QM1) CHANNEL(TO.QM1) CLUSTER(DEMO) DEFTYPE(CLUSSDRB) SSLCIPH( ) STATUS(RUNNING) One MQSC command read. No commands have a syntax error. All valid MQSC commands were processed. - To define new cluster sender with SSL on the other partial repository repeat steps 1 and 2 for QM4 replacing the parameters in bold.
To see the commands used to create the SSL channels, refer to script create_ssl_channels.bat in the Download section.
4. Verify the SSL channels are working
Next, test whether the new channels work correctly by starting all channels and checking the channel status.
- Start the channels on QM1
START CHL(TO.QM2.S)START CHL(TO.QM3.S)START CHL(TO.QM4.S) - Check that the channels from QM1 are in
RUNNINGstate andSSLPEERis non-blank (see Listing 7). A non-blankSSLPEERshows that the channel is using SSL. If the channels are not inRUNNINGstate check for error messages.DIS CHS(TO.QM2.S) SSLPEERDIS CHS(TO.QM3.S) SSLPEERDIS CHS(TO.QM4.S) SSLPEER
Listing 7. Starting and checking the channelsC:\>echo dis chs(TO.QM2.S) SSLPEER | runmqsc QM1 5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED. Starting MQSC for queue manager QM1. 1 : dis chs(TO.QM2.S) AMQ8417: Display Channel Status details. CHANNEL(TO.QM2.S) CHLTYPE(CLUSSDR) CONNAME(myhost2(1415)) CURRENT RQMNAME(QM2) STATUS(RUNNING) SUBSTATE(MQGET) SSLPEER(<Partner DN>) XMITQ(SYSTEM.CLUSTER.TRANSMIT.QUEUE) One MQSC command read. No commands have a syntax error. All valid MQSC commands were processed. C:\>echo dis chs(TO.QM3.S) SSLPEER | runmqsc QM1 5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED. Starting MQSC for queue manager QM1. 1 : dis chs(TO.QM3.S) AMQ8417: Display Channel Status details. CHANNEL(TO.QM3.S) CHLTYPE(CLUSSDR) CONNAME(myhost3(1416)) CURRENT RQMNAME(QM3) STATUS(RUNNING) SUBSTATE(MQGET) SSLPEER(<Partner DN>) XMITQ(SYSTEM.CLUSTER.TRANSMIT.QUEUE) One MQSC command read. No commands have a syntax error. All valid MQSC commands were processed. C:\>echo dis chs(TO.QM4.S) SSLPEER | runmqsc QM1 5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED. Starting MQSC for queue manager QM1. 1 : dis chs(TO.QM4.S) AMQ8417: Display Channel Status details. CHANNEL(TO.QM4.S) CHLTYPE(CLUSSDR) CONNAME(myhost4(1417)) CURRENT RQMNAME(QM4) STATUS(RUNNING) SUBSTATE(MQGET) SSLPEER(<Partner DN>) XMITQ(SYSTEM.CLUSTER.TRANSMIT.QUEUE) One MQSC command read. No commands have a syntax error. All valid MQSC commands were processed. - To start and check the channels on the other queue managers repeat steps 1 and 2 for QM2, QM3 and QM4 replacing the parameters in bold.
Check that the new SSL channels can transmit messages successfully
- Put messages to remote cluster queues and check that the messages arrive on the destination queues.
- Check that the messages were tranmitted over the SSL channels rather than the non-SSL channels by checking that the MSGS channel status parameter increments with each put:
DIS CHS(TO.*) WHERE(CHLTYPE EQ CLUSSDR) MSGS
The queue manager will workload balance messages to each channel depending on channel status and NETPRTY, as follows:
- SSL channel
NETPRTY= non-SSL channelNETPRTYIf both channels have equal status (e.g.
RUNNINGandRUNNING) the queue manager will workload balance messages round-robin to both channels. - SSL channel
NETPRTY> non-SSL channelNETPRTYIf both channels have equal status the queue manager will workload balance all messages to the SSL channel.
- SSL channel
NETPRTY< non-SSL channelNETPRTYIf both channels have equal status the queue manager will workload balance all messages to the non-SSL channel.
The queue manager will workload balance all messages to a channel if it has a more preferential channel status, regardless of NETPRTY.
NETPRTY is discussed further in the âSetting other configuration optionsâ section.
5. Delete the non-SSL channels
Once you verify that the SSL channels work, delete the non-SSL channels so that all cluster traffic is secure. If message affinities exist or messages are still being put to the SYSTEM.CLUSTER.TRANSMIT.QUEUE for the non-SSL channels, the messages could build up and become orphaned on the SYSTEM.CLUSTER.TRANSMIT.QUEUE.
You can reduce the risk of orphaning messages by stopping the non-SSL channels and only deleting them when you are certain they are not being used (i.e. no build up of messages on the SYSTEM.CLUSTER.TRANSMIT.QUEUE). When you stop the non-SSL channels the cluster workload algorithm is less likely to choose them unless an affinity exists. Once you are certain that the non-SSL channels are not being used, delete them.
Stop the non-SSL cluster sender channels
- Stop the non-SSL cluster sender channels on QM1 on myhost1.
STOP CHANNEL(TO.QM2)STOP CHANNEL(TO.QM3)STOP CHANNEL(TO.QM4) - Stop the non-SSL cluster sender channels on QM2 on myhost2.
STOP CHANNEL(TO.QM1)STOP CHANNEL(TO.QM3)STOP CHANNEL(TO.QM4) - Stop the non-SSL cluster sender channels on QM3 on myhost3.
STOP CHANNEL(TO.QM1)STOP CHANNEL(TO.QM2)STOP CHANNEL(TO.QM4) - Stop the non-SSL cluster sender channels on QM4 on myhost4.
STOP CHANNEL(TO.QM1)STOP CHANNEL(TO.QM2)STOP CHANNEL(TO.QM3)
To see the commands used to stop the non-SSL channels, refer to script stop_non_ssl_channels.bat in the Download section.
Check that the non-SSL cluster sender channels are not in-use
Check that there are no messages building up on the SYSTEM.CLUSTER.TRANSMIT.QUEUE for the stopped non-SSL channels. The CURDEPTH of the SYSTEM.CLUSTER.TRANSMIT.QUEUE indicates if messages have built up for any cluster sender channel, but XQMSGSA of channel status indicates if messages have built up for specific cluster sender channels. If there are messages building up, start the channels to let the messages flow and rectify the applications with the affinity before stopping the channel and checking again.
- Check that there are no messages building up for non-SSL cluster sender channels on QM1 on myhost1.
DIS CHS(TO.QM2) WHERE(XQMSGSA > 0)DIS CHS(TO.QM3) WHERE(XQMSGSA > 0)DIS CHS(TO.QM4) WHERE(XQMSGSA > 0)The commands should all return âChannel Status not found.â.
- Check that there are no messages building up for non-SSL cluster sender channels on QM2 on myhost2.
DIS CHS(TO.QM1) WHERE(XQMSGSA > 0)DIS CHS(TO.QM3) WHERE(XQMSGSA > 0)DIS CHS(TO.QM4) WHERE(XQMSGSA > 0) - Check that there are no messages building up for non-SSL cluster sender channels on QM3 on myhost3.
DIS CHS(TO.QM1) WHERE(XQMSGSA > 0)DIS CHS(TO.QM2) WHERE(XQMSGSA > 0)DIS CHS(TO.QM4) WHERE(XQMSGSA > 0) - Check that there are no messages building up for non-SSL cluster sender channels on QM4 on myhost4.
DIS CHS(TO.QM1) WHERE(XQMSGSA > 0)DIS CHS(TO.QM2) WHERE(XQMSGSA > 0)DIS CHS(TO.QM3) WHERE(XQMSGSA > 0)
To see the commands used to check the non-SSL channels, refer to script check_non_ssl_channels.bat in the Download section.
Delete the non-SSL cluster channels
Once the non-SSL channels are no longer in use they can be deleted.
- Delete the non-SSL cluster channels on QM1 on myhost1.
DELETE CHL(TO.QM1)DELETE CHL(TO.QM2) - Delete the non-SSL cluster channels on QM2 on myhost2.
DELETE CHL(TO.QM2)DELETE CHL(TO.QM1) - Delete the non-SSL cluster channels on QM3 on myhost3.
DELETE CHL(TO.QM3)DELETE CHL(TO.QM1) - Delete the non-SSL cluster channels on QM4 on myhost4.
DELETE CHL(TO.QM4)DELETE CHL(TO.QM2)
To see the commands used to delete the non-SSL channels, refer to script delete_non_ssl_channels.bat in the Download section.
Check that the non-SSL cluster queue manager objects have been deleted
- Ensure there are no non-SSL cluster queue manager objects on QM1 on myhost1:
DIS CLUSQMGR(*) WHERE(CHANNEL EQ TO.QM1)DIS CLUSQMGR(*) WHERE(CHANNEL EQ TO.QM2)DIS CLUSQMGR(*) WHERE(CHANNEL EQ TO.QM3)DIS CLUSQMGR(*) WHERE(CHANNEL EQ TO.QM4)The commands should all return
WebSphere MQ object not found. - Ensure there are no non-SSL cluster queue manager objects on QM2 on myhost2:
DIS CLUSQMGR(*) WHERE(CHANNEL EQ TO.QM1)DIS CLUSQMGR(*) WHERE(CHANNEL EQ TO.QM2)DIS CLUSQMGR(*) WHERE(CHANNEL EQ TO.QM3)DIS CLUSQMGR(*) WHERE(CHANNEL EQ TO.QM4) - Ensure there are no non-SSL cluster queue manager objects on QM3 on myhost3:
DIS CLUSQMGR(*) WHERE(CHANNEL EQ TO.QM1)DIS CLUSQMGR(*) WHERE(CHANNEL EQ TO.QM2)DIS CLUSQMGR(*) WHERE(CHANNEL EQ TO.QM3)DIS CLUSQMGR(*) WHERE(CHANNEL EQ TO.QM4) - Ensure there are no non-SSL cluster queue manager objects on QM4 on myhost4:
DIS CLUSQMGR(*) WHERE(CHANNEL EQ TO.QM1)DIS CLUSQMGR(*) WHERE(CHANNEL EQ TO.QM2)DIS CLUSQMGR(*) WHERE(CHANNEL EQ TO.QM3)DIS CLUSQMGR(*) WHERE(CHANNEL EQ TO.QM4)
This is the end of tasks required to enable SSL in the cluster.
If you encounter problems while enabling SSL you may want to turn off SSL. Three methods for achieving this are:
- Stopping the SSL channels
This method can be used up until Task 5. Once you define SSL channels there are two sets of channels between each queue manager (one SSL and one non-SSL). Manually stopping the SSL cluster sender channels will put them into STOPPED state, which is the least preferential state when the queue manager workload balances messages using the cluster workload algorithm. Therefore if the non-SSL channel is healthy, the queue manager should workload balance messages to the non-SSL channels. The queue manager will still workload balance messages to the SSL channels if there are affinities to them (e.g. If queues were opened bind-on-open and the open handle remains in use).
- Altering the SSL channels
You can use this method at any time. Altering the SSLCIPH attribute of the SSL channels to blank will turn off SSL for channels. Use the following command.
ALTER CHL(TO.<qm>) CHLTYPE(<CLUSRCVR/CLUSSDR>) SSLCIPH(â â)Alter the channels in the following order:
- All full repository cluster receivers.
- All full repository cluster senders.
- All partial repository cluster receivers.
- All partial repository cluster senders.
Use
DISPLAY CLUSQMGR(<qm>) SSLCIPHto check that all the change has been published to other cluster queue managers.After switching off SSL, to turn it back on there is no need to start from the beginning of this document; simply alter to channels to set the SSLCIPH attribute to a non-blank value.
- Deleting the SSL channels
You can use this method up until Task 5. For instructions on how to delete channels, see Task 5.
Setting other configuration options
Finally you can configure NETPRTY to direct the flow over messages over selected channels and set SSLCAUTH to further secure your cluster channels.
Channel network priority (NETPRTY) prioritises one set of channels over another, where the channels link the same two destinations. To minimize the risk of application outages when enabling SSL, you might want to set the channel network priority of the non-SSL channels to a value higher than that of the SSL channels. This prioritising may complicate the process because the default NETPRTY is zero, so before defining the SSL channels, you will need to alter all the non-SSL cluster receiver channels to have a NETPRTY greater than zero.
Setting the NETPRTY higher on non-SSL channels does not guarantee the non-SSL channels will transmit all messages. For example, imagine both the SSL and non-SSL channels from queue manager QMA to queue manager QMB are both in INACTIVE state and an application connects to QMA and starts putting messages to a queue on QMB. Because both channels statuses are equal, NETPRTY will choose the channel with higher network priority (i.e. the non-SSL channel). This triggers the non-SSL channel to start and so the non-SSL goes from INACTIVE to INITIALIZING to STARTING to BINDING to RUNNING. Whilst the non-SSL is in the intermediate states between INACTIVE and RUNNING it is less preferential in terms of channel state than the INACTIVE SSL channel. Therefore if the application puts messages while the non-SSL channel is starting up the queue manager could workload balance messages to the SSL channel.
If the NETPRTY of the SSL and non-SSL channels is equal, the queue manager will workload balance messages round robin to both channels. If the queue manager workload balances messages to the SSL channel, the SSL channel is not working, and the messages were put with bind-on-open, the messages will remain stuck on the SYSTEM.CLUSTER.TRANSMIT.QUEUE. If the queue manager workload balances messages to the SSL channel, the SSL channel is not working, and the messages were put with bind-not-fixed, the message will be re-workload balanced to the non-SSL channel (assuming the non-SSL channel is healthy).
SSLCAUTH defines whether or not the SSL server carries out an authentication check on the certificate for the SSL client. The SSL client is the channel that initiates the connection (i.e. for cluster channels, the cluster sender channel). The SSL server is the channel that accepts the connection (i.e. for cluster channels, the cluster receiver channel).
If SSLCAUTH is set to REQUIRED, the SSL server always carries out the authentication check. If SSLCAUTH is set to OPTIONAL and the SSL client does not have a certificate, the SSL server does not carry out the authentication check. If SSLCAUTH is set to OPTIONAL and the SSL client does have a certificate, the SSL server carries out the authentication check on the certificate for the SSL client. The SSL client always carries out an authentication check on the certificate for the SSL server. This authentication is key to SSL architecture and so there are no attributes to control SSL server certificate authentication.
In a cluster, all valid queue managers will have a certificate, so the client side always sends its certificate and the server always carries out an authentication check on it, regardless of the SSLCAUTH value.
Important: To prevent a invalid queue manager that does not hold a certificate from connecting to the cluster, all cluster channels in an SSL secured cluster should have SSLCAUTH set to REQUIRED.
This article serves as a starting point when designing procedures to enable SSL in an existing WebSphere MQ cluster. Before changing production systems, you should create a full set of instructions tailored to your cluster configuration and company procedures and testing those instructions in a test environment. You should adapt the instructions based on factors such as the cluster architecture and the location of the CA. Administrators that are familiar with clustering and SSL or working in non-critical environments may choose to omit some steps used to verify administration changes or even to enable SSL on the original cluster channels.
Appendix A â The pre-SSL cluster
This section contains the output from DIS CHL and DIS CLUSQMGR for the cluster before enabling SSL.
Listing 8. Output from DIS CHL(TO.*) on QM1
C:\>echo DIS CHL(TO.*) | runmqsc QM1
5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED.
Starting MQSC for queue manager QM1.
1 : DIS CHL(TO.*)
AMQ8414: Display Channel details.
CHANNEL(TO.QM1) CHLTYPE(CLUSRCVR)
AMQ8414: Display Channel details.
CHANNEL(TO.QM2) CHLTYPE(CLUSSDR)
One MQSC command read.
No commands have a syntax error.
All valid MQSC commands were processed. |
Listing 9. Output from DIS CHL(TO.*) on QM2
C:\>echo DIS CHL(TO.*) | runmqsc QM2
5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED.
Starting MQSC for queue manager QM2.
1 : DIS CHL(TO.*)
AMQ8414: Display Channel details.
CHANNEL(TO.QM1) CHLTYPE(CLUSSDR)
AMQ8414: Display Channel details.
CHANNEL(TO.QM2) CHLTYPE(CLUSRCVR)
One MQSC command read.
No commands have a syntax error.
All valid MQSC commands were processed. |
Listing 10. Output from DIS CHL(TO.*) on QM3
C:\>echo DIS CHL(TO.*) | runmqsc QM3
5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED.
Starting MQSC for queue manager QM3.
1 : DIS CHL(TO.*)
AMQ8414: Display Channel details.
CHANNEL(TO.QM1) CHLTYPE(CLUSSDR)
AMQ8414: Display Channel details.
CHANNEL(TO.QM3) CHLTYPE(CLUSRCVR)
One MQSC command read.
No commands have a syntax error.
All valid MQSC commands were processed. |
Listing 11. Output from DIS CHL(TO.*) on QM4
C:\>echo DIS CHL(TO.*) | runmqsc QM4
5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED.
Starting MQSC for queue manager QM4.
1 : DIS CHL(TO.*)
AMQ8414: Display Channel details.
CHANNEL(TO.QM2) CHLTYPE(CLUSSDR)
AMQ8414: Display Channel details.
CHANNEL(TO.QM4) CHLTYPE(CLUSRCVR)
One MQSC command read.
No commands have a syntax error.
All valid MQSC commands were processed. |
Listing 12. Output from DIS CLUSQMGR(*) on QM1
C:\>echo DIS CLUSQMGR(*) | runmqsc QM1
5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED.
Starting MQSC for queue manager QM1.
1 : DIS CLUSQMGR(*)
AMQ8441: Display Cluster Queue Manager details.
CLUSQMGR(QM1) CHANNEL(TO.QM1)
CLUSTER(DEMO)
AMQ8441: Display Cluster Queue Manager details.
CLUSQMGR(QM2) CHANNEL(TO.QM2)
CLUSTER(DEMO)
AMQ8441: Display Cluster Queue Manager details.
CLUSQMGR(QM3) CHANNEL(TO.QM3)
CLUSTER(DEMO)
AMQ8441: Display Cluster Queue Manager details.
CLUSQMGR(QM4) CHANNEL(TO.QM4)
CLUSTER(DEMO)
One MQSC command read.
No commands have a syntax error.
All valid MQSC commands were processed. |
Listing 13. Output from DIS CLUSQMGR(*) on QM2
C:\>echo DIS CLUSQMGR(*) | runmqsc QM2
5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED.
Starting MQSC for queue manager QM2.
1 : DIS CLUSQMGR(*)
AMQ8441: Display Cluster Queue Manager details.
CLUSQMGR(QM1) CHANNEL(TO.QM1)
CLUSTER(DEMO)
AMQ8441: Display Cluster Queue Manager details.
CLUSQMGR(QM2) CHANNEL(TO.QM2)
CLUSTER(DEMO)
AMQ8441: Display Cluster Queue Manager details.
CLUSQMGR(QM3) CHANNEL(TO.QM3)
CLUSTER(DEMO)
AMQ8441: Display Cluster Queue Manager details.
CLUSQMGR(QM4) CHANNEL(TO.QM4)
CLUSTER(DEMO)
One MQSC command read.
No commands have a syntax error.
All valid MQSC commands were processed. |
Listing 14. Output from DIS CLUSQMGR(*) on QM3
C:\>echo DIS CLUSQMGR(*) | runmqsc QM3
5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED.
Starting MQSC for queue manager QM3.
1 : DIS CLUSQMGR(*)
AMQ8441: Display Cluster Queue Manager details.
CLUSQMGR(QM1) CHANNEL(TO.QM1)
CLUSTER(DEMO)
AMQ8441: Display Cluster Queue Manager details.
CLUSQMGR(QM2) CHANNEL(TO.QM2)
CLUSTER(DEMO)
AMQ8441: Display Cluster Queue Manager details.
CLUSQMGR(QM3) CHANNEL(TO.QM3)
CLUSTER(DEMO)
AMQ8441: Display Cluster Queue Manager details.
CLUSQMGR(QM4) CHANNEL(TO.QM4)
CLUSTER(DEMO)
One MQSC command read.
No commands have a syntax error.
All valid MQSC commands were processed. |
Listing 15. Output from DIS CLUSQMGR(*) on QM4
C:\>echo DIS CLUSQMGR(*) | runmqsc QM4
5724-H72 (C) Copyright IBM Corp. 1994, 2004. ALL RIGHTS RESERVED.
Starting MQSC for queue manager QM4.
1 : DIS CLUSQMGR(*)
AMQ8441: Display Cluster Queue Manager details.
CLUSQMGR(QM1) CHANNEL(TO.QM1)
CLUSTER(DEMO)
AMQ8441: Display Cluster Queue Manager details.
CLUSQMGR(QM2) CHANNEL(TO.QM2)
CLUSTER(DEMO)
AMQ8441: Display Cluster Queue Manager details.
CLUSQMGR(QM3) CHANNEL(TO.QM3)
CLUSTER(DEMO)
AMQ8441: Display Cluster Queue Manager details.
CLUSQMGR(QM4) CHANNEL(TO.QM4)
CLUSTER(DEMO)
One MQSC command read.
No commands have a syntax error.
All valid MQSC commands were processed. |
| Name | Size | Download method |
|---|---|---|
| scripts.zip | 2 KB | HTTP |
Information about download methods
- Working with WebSphere MQ SSL support
-
WebSphere MQ V6 trial download
A no-charge trial download of WebSphere MQ V6. Includes limited online support for Windows® and Linux® installations at no charge during the trial period. -
WebSphere MQ V6 information center
A single Eclipse-based Web portal to all WebSphere MQ V6 documentation, with conceptual, task, and reference information on installing, configuring, and using your WebSphere MQ environment. -
WebSphere MQ documentation library
WebSphere MQ product manuals. -
WebSphere MQ product page
Product descriptions, product news, training information, support information, and more. -
WebSphere MQ SupportPacs
Downloadable code, documentation, and performance reports for the WebSphere MQ family of products. - WebSphere MQ public newsgroup
A non-IBM forum where you can get answers to your WebSphere MQ technical questions and share your WebSphere MQ knowledge with other users. - WebSphere Business Integration products page
For both business and technical users, a handy overview of all WebSphere Business Integration products - developerWorks WebSphere Business Integration zone
For developers, access to WebSphere Business Integration how-to articles, downloads, tutorials, education, product info, and more. - WebSphere forums
Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users. -
Most popular WebSphere trial downloads
No-charge trial downloads for key WebSphere products. - Trial downloads for IBM software products
No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products. - Safari Bookshelf: e-library designed for developers
Complete search and download access to thousands of technical books for a one-time subscription fee. Free trial for new subscribers. - developerWorks technical events and Webcasts
Free technical sessions by IBM experts that can accelerate your learning curve and help you succeed in your most difficult software projects. Sessions range from one-hour Webcasts to half-day and full-day live sessions in cities worldwide. - developerWorks blogs
Ongoing, free-form columns by software experts, to which you can add your comments. Check out Grady Booch's blog on software architecture.
Ian Vanstone is a Software Engineer on the WebSphere MQ Development team at the IBM Hursley Software Lab in the UK. He has worked on that team for the past five years and has given presentations at technical conferences on a variety of WebSphere MQ topics in the United States and Europe. You can contact Ian at ivans@uk.ibm.com.
Comments (Undergoing maintenance)





