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 IBM 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
SSL-Enabling the Custom Channel (Optional)
Configure the eG tests to use the custom channel and the credentials of the user to monitor queues and topics

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

Create a Queue Manager

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

crtmqm QM13

Note:

This step is not required if a queue manager of your choice is already available.

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

strmqm QM13

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 so as 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 is now created.

Creating a Custom Channel with Channel Authentication Records

Channel Authentication Records (CHLAUTH) are used to control who can connect to a channel, enhancing the security of communication between MQ Queue Managers. These records define rules to specify which users, or types of users, are allowed to use custom channels. To define a custom channel with Channel Authentication Record, you can use 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')

Property	Description
TYPE(ADDRESSMAP)	Allows you to map client IP addresses to a specific user for the purpose of channel authentication. This is useful when you want to control which users are allowed to connect to the MQ server from specific IP addresses
ADDRESS(*)	The channel authentication rule applies to all IP addresses. It doesn't restrict the rule to specific client addresses but instead applies universally to all clients attempting to connect, no matter their source IP.
USERSRC(CHANNEL)	Defines how the user for the connection is determined.The user context associated with the channel will be used for all incoming connections, rather than setting a static user or using a dynamic user mapping.
TYPE(BLOCKUSER)	Blocks specific users from accessing a given channel, regardless of other attributes like their IP address or the channel type
USERLIST('nobody')	Specifies that connections from the user "nobody" are to be blocked or rejected for the specified channel or channel authentication rule.

The custom WebSphere MQ channel with Channel Authentication Record is now 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 the IBM WebSphere MQ server.

SSL- Enabling the Custom Channel

In some high-security environments, administrators may want to ensure that the communication between the eG agent and the target IBM WebSphere MQ through the custom channel is safe and secure. To aid this, administrators can SSL-enable the custom channel that they have created for monitoring purpose. The SSL-enabled channel can now be used for both one-way and two-way SSL communication.

Note:

You can either use the server certificate and client certificate signed using an internal certificate authority i.e., self signed certificates to monitor the target IBM WebSphere MQ server using SSL enabled custom channel or using the server certificate and client certificate obtained from a valid certifying authority.

In the sections below, we have discussed on creating a self signed server certificate and client certificate only.

The steps to be followed to SSL-enable a channel is as follows:

Generate the key repository
Configure the Queue Manager
Enable One-way/Two-way SSL communication

Generating the Key Repository

To create a key repository to store the SSL certificates, you can use the ikeycmd tool on IBM WebSphere MQ.

Note:

The ikeycmd tool is available at:

<mqserver installation dir/mqm/java/jre64/jre/bin/ikeycmd on an IBM WebSphere MQ server installed on Microsoft Windows operating system or
/opt/mqm/java/jre64/jre/bin/ikeycmd on an IBM WebSphere MQ server installed on Linux operating system.

Creating a Server Database

Execute the below script to create a .kdb file as server database to store the server certificate:

ikeycmd -keydb -create -db "/path/to/ssl/key.kdb" -pw password -type cms -expire 1000 -stash

In our example, -db /path/to/ssl/key.kdb is the path where the key database (i.e., server database named key.kdb) will be stored in the queue manager QM13 i.e., /var/mqm/qmgrs/QM13/ssl/key.kdb and the password is serverpass. The script with the credentials are as follows:

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.

Creating a Client Database

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

ikeycmd -keydb -create -db "/path/to/client/egmqsslstore.jks" -pw password -type jks

In our example, -db /path/to/client/egmqsslstore.jks is the path where the client database will be stored in the eG agent i.e., -db /opt/egurkha/jre/lib/security/egmqsslstore.jks and the password is changeit. The script with the credentials are as follows:

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.

Configuring Queue Manager

To configure the queue manager with the location of the newly created server database, execute the following command from the MQSC command prompt :

ALTER QMGR SSLKEYR(‘/path/to/ssl/key.kdb')

In our example, /path/to/ssl/key.kdb is /var/mqm/qmgrs/QM13/ssl/key.kdb. The command to be executed therefore is:

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

Enabling One-Way SSL Communication

One-way SSL communication is a type of SSL/TLS encryption where the server(Queue Manager) proves its identity to the client (eG agent), but the client does not need to prove its identity to the server. For one-way SSL, you need:

A server certificate on the server side (the Queue Manager which generates the server certificate).
A truststore (a keystore or client database) that contains the trusted certificate authority (CA) certificates that can validate the server certificate.

The client(eG agent) only needs to trust the server's certificate, so the client will have the server’s CA certificate in its truststore.

Creating a Self Signed Server Certificate

To create a server certificate in the server database, use the following command:

ikeycmd -cert -create -db "/path/to/ssl/key.kdb" -pw <password> -label <unique name of the certificate+name of the queue manager> -dn "distinguished name that includes Common Name, organization and Country" -expire 1000 -sig_alg SHA256_WITH_RSA

In our example, /path/to/ssl/key.kdb is /var/mqm/qmgrs/QM13/ssl/key.kdb, -label is ibmwebspheremqqm13 and -dn is CN=QM13,OU=eG,O=eG Innovations,C=IN. Therefore, your command for execution is as follows:

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

Extracting the Public Part of Server Certificate

Now, extract the public part of the server certificate using the following command:

ikeycmd -cert -extract -db "/path/to/ssl/key.kdb" -pw <password> -label <unique name of the certificate+name of the queue manager> -target <name of the temporary server certificate>.crt -format ascii

In our example, /path/to/ssl/key.kdb is /var/mqm/qmgrs/QM13/ssl/key.kdb, unique name of the certificate+name of the queue manager is ibmwebspheremqqm13 and name of the temporary server certificate is QM13.Your command for execution is therefore:

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

Adding the Server Certificate to Client Database

Once you have extracted the public part of the server certificate, add the certificate to the client database located in /path/to/client/<name of client database>.jks. For this, use the following command:

ikeycmd -cert -add -db "/path/to/client/<name of client database>.jks" -pw <password of the client database> -label <unique name of the certificate+name of the queue manager> -file <name of the temporary server certificate>.crt -format ascii

In our example, /path/to/client/<name of client database>.jks is /opt/egurkha/jre/lib/security/egmqsslstore.jks, password is changeit, unique name of the certificate+name of the queue manager is ibmwebspheremqqm13 and name of the temporary server certificate is QM13.

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

Enabling One-Way SSL Communication on the Channel

To SSL-enable the channel for one-way communication, execute the following command:

ALTER CHL(channel name) CHLTYPE(SVRCONN) SSLCIPH(TLS_RSA_WITH_AES_128_CBC_SHA256) SSLCAUTH(OPTIONAL)

In our example, the channel name is CLNT.EG.SVRCONN.

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

REFRESH SECURITY(*)

If you are using an SSL enabled channel with one way communication for monitoring the IBM WebSphere MQ server, then specify "/opt/egurkha/jre/lib/security/egmqsslstore.jks" against the TRUSTSTORE parameter in the test configuration page.

The SSLCIPH value is specified against the SSL Cipher Spec parameter in the test configuration page.

Note:

The SSLCIPH value may differ based on the version of the target IBM WebSphere MQ server being monitored or based on the SSL/TLS libraries (like IBM Global Security Kit (GSKit) or OpenSSL) used in different MQ versions.

Enabling Two-Way SSL Communication

Two-way SSL (Secure Sockets Layer) communication, also known as mutual SSL/TLS authentication, is a security mechanism where both the client (eG agent) and the server (Queue Manager) authenticate each other using SSL/TLS certificates. This ensures that both parties are verified, providing strong security for data in transit.

In addition to the steps mentioned in Enabling One-Way SSL Communication, you should fulfill the following steps too:

Creating a Self Signed Client Certificate

To create a client certificate, use the following command:

ikeycmd -cert -create -db "/path/to/client/<name of client database>.jks" -pw <password> -label <name of the client certificate+name of user authorized to access the client> -dn "<distinguished name that includes Common Name, organization and Country>" -expire 730

In our example, /path/to/client/<name of client database>.jks is /opt/egurkha/jre/lib/security/egmqsslstore.jks, password is changeit, name of the client certificate+name of user authorized to access the client is ibmwebspheremqegurkha and distinguished name that includes Common Name, organization and Country is CN=egurkha,OU=eG,O=eG Innovations,C=IN. Therefore, execute the following command:

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

Extracting the Public Part of Client Certificate

To extract the public part of the client certificate, use the following command:

ikeycmd -cert -extract -db "/path/to/client/<name of client database>.jks" -pw password -label <name of the client certificate+name of user authorized to access the client> -target <name of temporary client certificate>.crt -format ascii

In our example, /path/to/client/<name of client database>.jks is /opt/egurkha/jre/lib/security/egmqsslstore.jks, password is changeit, name of the client certificate+name of user authorized to access the client is ibmwebspheremqegurkha and name of temporary client certificate is egagentmqsslclient. Therefore, the command to be executed is as follows:

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

Adding the Client Certificate to Server Database

To add the client certificate to the server database, use the following command:

ikeycmd -cert -add -db "/path/to/ssl/key.kdb" -pw <password to server database> -label <name of the client certificate+name of user authorized to access the client> -file <name of temporary client certificate>.crt -format ascii

In our example, /path/to/ssl/key.kdb is /var/mqm/qmgrs/QM13/ssl/key.kdb, password to server database is serverpass, name of the client certificate+name of user authorized to access the client is ibmwebspheremqegurkha and name of temporary client certificate is egagentmqsslclient. Therefore, the command to be executed is:

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

Enabling Two-Way SSL Communication on the Channel

To SSL-enable the channel for two-way communication, execute the following command:

ALTER CHL(channel name) CHLTYPE(SVRCONN) SSLCIPH(TLS_RSA_WITH_AES_128_CBC_SHA256) SSLCAUTH(REQUIRED)
REFRESH SECURITY(*)

In our example, the channel name is CLNT.EG.SVRCONN. Therefore, your command will be:

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 are using an SSL enabled channel with two way communication for monitoring the IBM WebSphere MQ server, then specify "/opt/egurkha/jre/lib/security/egmqsslstore.jks" against the TRUSTSTORE parameter and the KEYSTORE parameter in the test configuration page. This way, the eG agent can access the keystore location and present the client certificate to the server and let the server authenticate this against the one contained in the server database.

Troubleshooting

Disabling SSL on a Custom Channel

To disable SSL on a custom channel (i.e., to convert an SSL-enabled channel to a non SSL-enabled channel), you can simply use the following command:

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

REFRESH SECURITY(*)

Here, CLNT.EG.SVRCONN is an example of the channel name.

Type QUIT to exit the MQSC interface.

How to Check if the Channel is SSL-Enabled or Not?

To check if a channel is SSL-enabled or not, execute the following command:

dis chl (CHANNEL_NAME)SSLCIPH SSLCAUTH

In our example, CHANNEL_NAME is CLNT.EG.SVRCONN. Therefore, execute the following command:

dis chl (CLNT.EG.SVRCONN)SSLCIPH SSLCAUTH

In the command output, 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, i.e., a valid cipher such as TLS_RSA_WITH_AES_128_CBC_SHA256, then it is an SSL-enabled channel.

Note:

This cipher value is specified against the SSL Cipher Spec parameter while configuring the tests for target MQ server.

If the channel is SSL-enabled, to figure out whether the SSL communication is one-way or two-way, check the SSLCAUTH parameter.

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

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

Listing the Certificates Available in Client Database

To list the certificates available in the client database, use the following command:

ikeycmd -cert -list -db "/path/to/client/<name of client database>.jks" -pw password

Here, /path/to/client/<name of client database>.jks is /opt/egurkha/jre/lib/security/egmqsslstore.jks and password is changeit.

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

This way, you can ensure that your newly created client certificate is available in the client database.

Listing the Certificates Available in Server Database

To list the certificates available in the server database, use the following command:

ikeycmd -cert -list -db "/path/to/ssl/key.kdb" -pw password

In our example, /path/to/ssl/key.kdb is /var/mqm/qmgrs/QM13/ssl/key.kdb and password is serverpass. Therefore, your command will be:

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

This way, you can ensure that your newly created client certificate is available in the client database.