Configuring the eG Agent to Monitor the Queue Manager

Typically, to monitor a queue manager, the eG agent needs to be configured with access to the default server connection channel on WebSphere MQ – i.e., the SYSTEM.DEF.SVRCONN channel. In high security environments however, administrators may prefer not to expose this default channel and its access privileges to the eG agent. In such environments therefore, you need to do the following to enable the eG agent to monitor the queue manager:

Create a Queue manager
Create a Custom Channel
Configure the eG tests to use the custom channel and the credentials of the user to monitor queues and topics
Configure SSL authentication on the eG agent and queue manager.

Let us now discuss each of the steps mentioned above in the upcoming sections.

Create a queue manager

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

To create a queue 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

Type END to exit the MQSC interface.

Creating a Custom Channel

To create a custom channel for monitoring a Queue manager, do the following:

Execute the following command from the bin directory of the MQ Install directory to start the MQ Series commands (MQSC) for the queue manager:

runmqsc <Queue Manager name>

For example, if the name of the Queue manager is QM13, then the command will be as follows:

runmqsc QM13

Once the MQSC is started, you can execute commands to create a custom channel. Say for example, the name of the custom channel is CLNT.EG.SVRCONN, execute the commands in the command prompt as follows:

DEFINE CHANNEL<CLNT.EG.SVRCONN> CHLTYPE<SVRCONN> TRPTYPE<TCP>

If you wish to add a description to the custom channel, then you can do so by adding a DESCR section to the above mentioned command. In our example, the description is Server-Connection channel for eG. Therefore the command that needs to be executed is as follows:

DEFINE CHANNEL<CLNT.EG.SVRCONN> CHLTYPE<SVRCONN> TRPTYPE<TCP> DESCR<Server-Connection channel for eG >

If the command exceeds the stipulated number of characters that need to be typed in the command prompt, then the command can be split by a ‘+’ symbol. In such cases, the command can be executed as follows:

DEFINE CHANNEL<CLNT.EG.SVRCONN> CHLTYPE<SVRCONN> TRPTYPE<TCP> +

DESCR<Server-Connection channel for eG >

The custom WebSphere MQ channel will now be created. For a custom channel to take effect in the WebSphere MQ server, either the security cache or the queue manager of the server needs to be refreshed. If the queue manager is refreshed, the current messages of the server may get deleted. Therefore, refresh the security cache by issuing the following command:

REFRESH SECURITY<*>

Once the security cache is refreshed successfully, you can stop the MQ Series commands by issuing the END command.

The custom channel is now ready for monitoring WebSphere MQ server.

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.You can communicate with the target MQ server through non-SSL and SSL enabled channel.

To define a non -SSL channel and create or modify channel authentication record, run the following script in the terminal:

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(*)

In the above mentioned command SET CHLAUTH section is used to create or modify channel authentication records. The TYPE parameter denotes type of channel authentication record for which to set allowed partner details or mappings to the channel. The BLOCKUSER channel authentication record prevents a specified user or users from connecting. Here, in this example users named "nobody" are blocked from connecting to the channel. The ADDRESSMAP channel authentication record maps IP addresses to the specified channel. The addresses given in the ADDRESS filter is mapped to the specified channel. In the above example an asterick "*" value for ADDRESS filter denotes that all addresses are allowed to access the channel.

If SSL enabled channel is used for communication, then for configuring SSL authentication, follow the steps below:

Enabling communication through 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.

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 MQ 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 contained 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 contained 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 contained in the server database.

Configuring queue manager

Now you have to change the default key repository 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 check if the channel is SSL enabled or not?

To check whether the channel used for communication with the target MQ server is SSL enabled or not, 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 not 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.