Pre-Requisites for Monitoring IBM WebSphere MQ Servers

  1. To monitor the IBM WebSphere MQ server, the eG agent installed user should be within the MQM installed user group.
  2. The eG agent should be bundled with JRE 1.7.

  3. For monitoring IBM WebSphere MQ server version 6 and below, the following jar files need to be copied from the [WebSphere MQ install directory/java/lib] directory to the <EG_INSTALL_DIR>/lib directory:

    • com.ibm.mq.jar
    • connector.jar
    • com.ibm.mq.pcf.jar

  4. For monitoring WebSphere MQ version 7.0, the following jar files need to be copied to the <EG_INSTALL_DIR>/lib directory:

    • com.ibm.mq.jar
    • com.ibm.mq.jmqi.jar
    • com.ibm.mq.headers.jar
    • com.ibm.mq.pcf.jar
    • com.ibm.mq.commonservices.jar
    • connector.jar

    After copying the jar files, remember to restart the eG agent. If MQ monitoring is done in an agentless manner, these jar files should be available on the remote agent that will perform the monitoring.

  5. For monitoring WebSphere MQ version 8.0, the following jar files need to be copied to the <EG_INSTALL_DIR>/lib directory:

    • com.ibm.mq.jar
    • com.ibm.mq.jmqi.jar
    • com.ibm.mq.headers.jar
    • com.ibm.mq.pcf.jar
    • com.ibm.mq.commonservices.jar

    After copying the jar files, remember to restart the eG agent. If MQ monitoring is done in an agentless manner, these jar files should be available on the remote agent that will perform the monitoring.

  6. For monitoring WebSphere MQ version 9.0 and above, only the following jar file need to be copied to the <EG_INSTALL_DIR>/lib directory:

    • com.ibm.mq.allclient.jar

    After copying the jar file, remember to restart the eG agent. If MQ monitoring is done in an agentless manner, these jar file should be available on the remote agent that will perform the monitoring.

  7. Configure the eG agent to monitor the queue manager and its queues and topics.

Enabling communication through SSL enabled channel

You can communicate with the target MQ server through non-SSL enabled and SSL enabled channel. If SSL enabled channel is being used for communication, then you can use one-way or two-way SSL authentication. To enable eG agent to use SSL enabled channel for communication with the target MQ server the following prerequisites must be fulfilled.

Create a queue manager

Note: This step is not required if queue manager is already available.

To create a queeu manager execute the following command from the bin directory of the MQ Install directory to start the MQ Series commands (MQSC) for the queue manager:

  • To create a queue manager called QM13, execute the following command in the terminal,

    crtmqm QM13

  • Now, to start the queue manager, run the below command:

    strmqm QM13

  • Then, run the newly created queue manager with the following command:

    runmqsc QM13

  • To create or define a non -SSL channel, run the following script:

    DEFINE CHANNEL(CLNT.EG.SVRCONN) CHLTYPE(SVRCONN) TRPTYPE(TCP)

    SET CHLAUTH(CLNT.EG.SVRCONN) TYPE(ADDRESSMAP) ADDRESS(*) USERSRC(CHANNEL)

    SET CHLAUTH(CLNT.EG.SVRCONN) TYPE(BLOCKUSER) USERLIST('nobody')

    REFRESH SECURITY(*)

  • Type end to exit the MQSC interface.

After creating and setting up the queue manager, you have to create and configure SSL authentication on the eG agent and queue manager to enable the communication between the target server and agent for collecting metrics. For configuring SSL authentication, follow the steps below:

Enabling one-way SSL authentication

One-way SSL authentication requires truststore on the client and keystore on the server. The client validates the keystore certificate against the certificates in the truststore. If the certificate is found in truststore, the client accepts communication from SSL server. For this,

We are using ikeycmd program to create and configure SSL certificate, which is located in MQ Install directory. For Windows: <mqserver installation dir/mqm/java/jre64/jre/bin/ikeycmd, and for Linux:/opt/mqm/java/jre64/jre/bin/ikeycmd .

  • Create a .jks file as client database in the eG agent using the command given below:

    ikeycmd -keydb -create -db "/opt/egurkha/jre/lib/security/egmqsslstore.jks" -pw changeit -type jks

    Note: If client database already exists, then you can skip the above step.

  • Now, execute the below script to create a .kdb file as server database to store server certificate:

    ikeycmd -keydb -create -db "/var/mqm/qmgrs/QM13/ssl/key.kdb" -pw serverpass -type cms -expire 1000 -stash

    Note: If server database already exists, then you can skip the above step.

  • Then, create a server certificate in this .kdb file using the below command:

    ikeycmd -cert -create -db "/var/mqm/qmgrs/QM13/ssl/key.kdb" -pw serverpass -label ibmwebspheremqqm13 -dn "CN=QM13,OU=eG,O=eG Innovations,C=IN" -expire 1000 -sig_alg SHA256_WITH_RSA

    By default, the certificate name is given as 'ibmwebspheremq’ + ‘queue manager name’, here for instance the certificate name is ibmwebpsheremqqm13.

  • If you want to check if the certificate is conatined in the kdb database file, execute the following command:

    ikeycmd -cert -list -db "/var/mqm/qmgrs/QM13/ssl/key.kdb" -pw serverpass

    This will display the list of certificates conatined in the kdb file. In this case, check for certificate with name ibmwebpsheremqqm13.

  • Execute the following command and extract the public part of the server certificate:

    ikeycmd -cert -extract -db "/var/mqm/qmgrs/QM13/ssl/key.kdb" -pw serverpass -label ibmwebspheremqqm13 -target QM13.crt -format ascii

  • Then,add this certificate to the client jks file, that is located in /opt/egurkha/jre/lib/security/egmqsslstore.jks. For this run the command below:

    ikeycmd -cert -add -db "/opt/egurkha/jre/lib/security/egmqsslstore.jks" -pw changeit -label ibmwebspheremqqm13 -file QM13.crt -format ascii

  • Now, confirm whether the certificate is present in the client jks file by executing the following script:

    ikeycmd -cert -list -db "/opt/egurkha/jre/lib/security/egmqsslstore.jks" -pw changeit

    This will display the list of certificates in the client jks file.

  • If you are using one-way SSL authentication, then specify "/opt/egurkha/jre/lib/security/egmqsslstore.jks" as the truststore location while configuring tests for the target server.

Enabling two-way SSL authentication

In case of two-way SSL authentication. the client authenticate the server and the server authenticate the client. Two-way SSL authentication requires truststore and keystores in both client and server. For this, first follow the above mentioned steps for configuring one-way authentication, and then execute the steps given below:

  • Now, since you have already created a server database and client database, next step is to create a client certificate in the client database using the command given below:

    ikeycmd -cert -create -db "/opt/egurkha/jre/lib/security/egmqsslstore.jks" -pw changeit -label ibmwebspheremqegurkha -dn "CN=egurkha,OU=eG,O=eG Innovations,C=IN" -expire 730

    By default, the certificate name is given as ibmwebspheremq’ + ‘client username’, here for instance the certificate name is ibmwebspheremqegurkha.

  • Then, run the given script to check if the above created certificate is present in the client database:

    ikeycmd -cert -list -db "/opt/egurkha/jre/lib/security/egmqsslstore.jks" -pw changeit

    This will display the list of certificates conatined in the jks file. In this case, check for certificate with name ibmwebspheremqegurkha.

  • Execute the following command and extract the public part of the client certificate:

    ikeycmd -cert -extract -db "/opt/egurkha/jre/lib/security/egmqsslstore.jks" -pw changeit -label ibmwebspheremqegurkha -target egagentmqsslclient.crt -format ascii

  • Next, add this certificate to the server kdb file, that is located in /var/mqm/qmgrs/QM13/ssl/key.kdb. For this run the given command:

    ikeycmd -cert -add -db "/var/mqm/qmgrs/QM13/ssl/key.kdb" -pw serverpass -label ibmwebspheremqegurkha -file egagentmqsslclient.crt -format ascii

  • Now confirm whether the certificates are present in the server database using the following script:

    ikeycmd -cert -list -db "/var/mqm/qmgrs/QM13/ssl/key.kdb" -pw serverpass

    This will display the list of certificates in the server kdb file.

  • If you are using two-way SSL authentication, then specify "/opt/egurkha/jre/lib/security/egmqsslstore.jks" as the keystore location while configuring tests for the target server. This way the eG agent can access the keystore location and present the client certificate to the server and server authenticates this against the one conatined in the server database.

Configuring queue manager

Now you have to change the default key depository of the queue manager to the above created key database. For this open the MQSC command prompt and redirect to IBM Install dir\bin. For windows, C:\Program Files\IBM\MQ\bin, for Linux execute this command:/opt/mqm/bin

  • Then, change the location of the queue manager's key database file using the given script:

    ./runmqsc QM13

    ALTER QMGR SSLKEYR(‘/var/mqm/qmgrs/QM13/ssl/key')

    The key database file has the fully-qualified filename: /var/mqm/qmgrs/QM13/ssl/key.kdb

    Note:

    The .kdb extension is a mandatory part of the filename, but is not included as part of the value of the parameter.

  • Now, alter the above created non-SSL channel for configuring one-way and two-way SSL authentication. For one-way communication, execute the given command:

    ALTER CHL(CLNT.EG.SVRCONN) CHLTYPE(SVRCONN) SSLCIPH(TLS_RSA_WITH_AES_128_CBC_SHA256) SSLCAUTH(OPTIONAL)

    REFRESH SECURITY(*)

  • If you are using two-way authentication, run the below script:

    ALTER CHL(CLNT.EG.SVRCONN) CHLTYPE(SVRCONN) SSLCIPH(TLS_RSA_WITH_AES_128_CBC_SHA256) SSLCAUTH(REQUIRED)

    REFRESH SECURITY(*)

  • Type quit to exit the MQSC interface.

  • If you need to remove the SSL configuration for this channel, use the command given below:

    ALTER CHL(CLNT.EG.SVRCONN) CHLTYPE(SVRCONN) SSLCIPH( '' ) SSLCAUTH(REQUIRED)

    REFRESH SECURITY(*)

    Type quit to exit the MQSC interface.

How to delete the certificate in the key database?

  • To delete the certificate contained in client jks file, run the given command:

    /opt/egurkha/jre/keytool -delete -keystore "/opt/egurkha/jre/lib/security/egmqsslstore.jks " -storepass changeit -alias ibmwebspheremqqm13 -type jks

    This will delete the certificate named ibmwebspheremqqm13 from the client database.

  • To delete the certificate contained in the server kdb file, execute the following script:

    /opt/mqm/bin/runmqckm -cert -delete -label ibmwebspheremqegurkha -db "/var/mqm/qmgrs/QM13/ssl/key.kdb" -pw serverpass

    This will delete the certificate named ibmwebspheremqegurkha from the server database.

How to check if the channel is SSL enabled or not?

To check whether the channel used for communication with the target MQ server is non-SSL or SSL enabled, follow the steps given below:

  • Open a command window and execute the following command to run the QM13 queue manager, where QM13 denotes the queue manager name;

    runmqsc QM13

  • Now run the below command with the specific channel name to display that channel:

    dis chl (CHANNEL_NAME)SSLCIPH SSLCAUTH

  • Now check the SSLCIPH parameter. If the parameter is empty, then the channel is non-SSL enabled. However, if there is a specified value for this parameter, that is a valid cipher such as, TLS_RSA_WITH_AES_128_CBC_SHA256. Then it is an SSL-enabled channel. This cipher value must be specified against the SSL Cipher Spec parameter while configuring the tests for target MQ server.

  • If the channel is SSL-enabled then to find whether the SSL communication is one-way ot two-way, check the SSLCAUTH parameter.

    If the SSLCAUTH value is REQUIRED, then its two-way communication.

    If the SSLCAUTH value is OPTIONAL, then its one-way communication.