IBM MQ

Prerequisites

  • IBM MQ 8.0+ for Windows/Linux/AIX
  • An Environment ActiveGate (version 1.155+) that has the ActiveGate plugin module installed and isn't used for synthetic or mainframe monitoring
    • 1 environment ActiveGate can typically support 30-50 IBM MQ queue managers
  • IBM MQ client installed on Environment ActiveGate
  • A server-connection channel on the queue manager for communication with the plugin

Interested in monitoring IBM MQ with Dynatrace?

The quickest way to get started is by contacting a Dynatrace ONE product specialist. Just click the chat button in the upper-right corner of the Dynatrace menu bar.

Environment ActiveGate installation

ActiveGate plugin module installation

IBM MQ Client Installation

See the current version here. Alternatively, you can search the IBM website for the MQ client version download that matches your environment.

  • For Windows, install the MQ client as specified.
  • Note that for Linux-based ActiveGates, you only need to install MQSeriesRuntime.rpm and MQSeriesClient.rpm.
    1. Add the MQ client lib64 libraries to LD PATH by creating a new file in /etc/ld.so.conf.d/.
    2. Enter a line that points to the lib64 libraries. The default is /opt/mqm/lib64.
    3. Save and restart the LD configuration with sudo ldconfig.

Extension installation

  1. Obtain the install file (custom.remote.python.ibmmq.zip). Don't rename the file.

  2. Unzip custom.remote.python.ibmmq.zip to the plugin_deployment directory of your ActiveGate host.

  3. If the resulting directory structure isn't .\plugin_deployment\custom.remote.python.ibmmq\, please make the neccessary changes.

  4. Restart the Dynatrace Remote Plugin Module service.

    • On Linux, restart the service using the following commands with admin rights:
      • systemctl restart remotepluginmodule.service
    • On Windows, run these two commands in a Command Prompt launched as Admin:
      • sc stop "Dynatrace Remote Plugin Module"
      • sc start "Dynatrace Remote Plugin Module"
  5. Return to the Dynatrace web UI. Click Settings, the Add new technology monitoring button, and finally the Add ActiveGate plugin button.

  6. Click the Upload plugin button and upload custom.remote.python.ibmmq.zip.

  7. Enter the following information to connect to your IBM MQ Queue Manager:

    • Endpoint name: Type a meaningful endpoint name.
    • User: The username for connecting to the IBM MQ instance.
    • Password: The user password.
    • Comma-separated Queue Manager hosts:ports: IP(port) or hostname(port)
    • Server-connection channel: Name of communication channel
    • Single queue manager: My_qmgr_name
    • Channels: Leave empty for none, abc* (to include), or -abc* (to exclude)
    • Comma seperated queues: Queue1, Que* (to include); -UnwantedQu* (to exclude)
    • Exclude System queues
    • Run Rest Stats on Queues: retrieves Deq/Enq
    • Listener channels: Leave empty for none, * for all
    • Path to key repository: If using SSL, key repository location must be provided and the below conditions must be satisfied:
      • Two key repositories must exist - one on the ActiveGate where the MQ Client resides, and the other on the IBM MQ server.
      • Each repository must have the other’s public key certificate.
      • The certificate label of the MQ Server must be ibmwebspheremq<queue_manager>(all lowercase).
      • The certificate label of the MQ Client on the ActiveGate must be ibmwebspheremq<username> (all lowercase).
      • The username is the account through which the Remote Plugin process runs.
    • Cipher spec
    • Name of group: If queue manager is part of a cluster, type the name here to group in the GUI.
    • Output debug: Only enable if requested by Dynatrace.

    IBM MQ

Installation troubleshooting

  • Error (libmqic_r.so: cannot open shared object file: No such file or directory)
    • See the IBM MQ client installation section for details. This error is likely caused by the IBM MQ client not being installed on the ActiveGate host, or the path hasn't been updated to point to the libmqic_r.so.
  • Update failed - Authorization error Connection failed. Unauthorized user <username>. FAILED: MQRC_NOT_AUTHORIZED
    • Either the provided user wasn't added to the IBM MQ environment or the password is incorrect. Note that the password isn't applied automatically during updates; you need to manually add the password again.
  • Troubleshooting ActiveGate plugin installation issues

SSL configuration

Self-signed certificates

  1. Your keystore on your MQ server must have a certificate with the proper label. Your keystore can have any name, but the certificate label is what is important. It will not accept any other format. Format is: ibmwebspheremq<queue_manager_lower_case> where <queue_manager_lower_case> is the name of your queue manager. So if your queue manager is QM_ORANGE, then the certificate label must be ibmwebspheremqqm_orange

    • You can create a new keystore on your MQ server with the following command: /opt/mqm/bin/runmqakm -keydb -create -db /var/mqm/qmgrs/QM_ORANGE/ssl/qm_orange.kdb -pw changeit -type cms -stash

    • Then you can create the certificate into the keystore with the following command: /opt/mqm/bin/runmqakm -cert -create -db /var/mqm/qmgrs/QM_ORANGE/ssl/qm_orange.kdb -pw changeit -label ibmwebspheremqqm_orange -size 2048 -sigalg SHA512withRSA -san_dnsname qm_orange.dynatrace.com -dn "CN=qm_orange.dynatrace.com,OU=Extensions,O='Dynatrace',L='Detroit',ST=Michigan,C=US" -expire 1825

    • Note: The filename can be anything, and the location of the keystore is your preference. The example below uses the default location which reflects the same location in the Queue Manager properties page.

  2. Your keystore on you client side (where ActiveGate is, where your MQ client is installed) must have a certificate with the proper label. Your client keystore can have any name but the certificate label is what is important. It won't accept any other format. Format is: ibmwebspheremq<user_running_plugin_process> where <user_running_plugin_process> is the operating system user that is running the Dynatrace Remote Plugin process/service (not the ActiveGate). If it’s Windows, then it's likely that it’s using “Local Service” as the account that runs it and you should change it to a real user (service account, for example). So if the user is svcdyn then the certificate label on the client must be ibmwebspheremqsvcdyn. SSL Create the client certificate in the client keystore: SSL Username running the process must match username in the client certificate: SSL SSL

  3. Both keystores on the MQ server and the MQ client (where ActiveGate is) have to be in CMS format (not JKS or PK12) and must contain .kdb, .rdb, .sth files at least. STH is the stashed password so make sure to stash the password when you create the keystore.

    MQ server: SSL ActiveGate: SSL

  4. Client keystore must have the public key of the MQ Server certificate imported. So export the certificate ibmwebspheremq<queue_manager> from the MQ server keystore and import it into the client keystore.

    You can export the certificate from the MQ server keystore by using the following command: /opt/mqm/bin/runmqakm -cert -extract -db /var/mqm/qmgrs/QM_ORANGE/ssl/qm_orange.kdb -pw changeit -label ibmwebspheremqqm_orange -target /var/mqm/qmgrs/QM_ORANGE/ssl/ibmwebspheremqqm_orange.arm -format ascii

    Copy the extracted certificate file to the ActiveGate, then import the extracted certificate into the ibmmqkeystore.kdb keystore on the ActiveGate: SSL

  5. MQ server keystore must have the public key of the client certificate imported. So export the certificate ibmwebspheremq<username> from the client keystore and import it into the MQ server keystore.

    Export the certificate from the ActiveGate keystore: SSL

    Copy the extracted client certificate to the MQ server then import it using the following command:

    /opt/mqm/bin/runmqakm -cert -add -db /var/mqm/qmgrs/QM_ORANGE/ssl/qm_orange.kdb -pw changeit -label ibmwebspheremq**diego** -file /var/mqm/qmgrs/QM_ORANGE/ssl/client_cert.arm -format ascii

  6. Now your MQ server should have a keystore with its own certificate and the client certificate, and your ActiveGate should have its own keystore with its own certificate and the MQ server certificate. You can list the certificates in MQ server keystore with the following command: /opt/mqm/bin/runmqakm -cert -list -db /var/mqm/qmgrs/QM_ORANGE/ssl/qm_orange.kdb -pw changeit

    SSL

    ActiveGate keystore showing imported certificate from MQ server: SSL

  7. Make sure that your server-connection channel has the proper cipher spec selected and you select the exact same spec in the plugin configuration UI. SSL

  8. If you're using a Peer Name (PNRP) on the server-connection channel (Distinguished Name), then make sure that the Distinguished Name exists in the CLIENT certificate (the one labeled ibmwebspheremq<user>)

  9. The path to the repository field on the plugin UI is the path to the client keystore, including the keystore name without the extension. So if the keystore is D:\ssl\clientkeystore.kdb then the path to repository field must say: D:\ssl\clientkeystore

### CA-signed certificates

  1. Your MQ server and MQ client (ActiveGate) need to have separate CMS keystores. They must be CMS, not JKS or PK12 or other. The name of your keystores doesn't matter.

  2. Your MQ server keystore must have your CA root certificate imported as a “Signer Certificate”. SSL

  3. You must create a Certificate Signer Request (CSR) from your MQ server keystore because it writes a record in the .rdb file of your keystore. You can't create a CSR from elsewhere. SSL

  4. Create a signed certificate using your Certificate Authority and your Signer Request. For OpenSSL, you could execute the following command: openssl x509 -req -in certcsr.arm -CA myCARoot.crt -CAkey myCARoot.key -CAcreateserial -out mysignedcert.crt -days 500 -sha256

  5. Import/Receive your signed certificate into your keystore in Personal Certificates. Make sure your certificate has the label (alias) ibmwebspheremq<queue_manager> where <queue_manager> is your queue manager name all in lower case. SSL

  6. Repeat steps 2-4 for your MQ client (ActiveGate) keystore.

  7. Import/Receive your signed certificate into your keystore in “Personal Certificates”. Make sure your certificate has the label (alias) ibmwebspheremq<username> where <username> is the user that runs your Remote Plugin Module process (not your ActiveGate process). SSL

  8. When done, place all files for MQ server in the proper location and configure the Queue Manager to look for the keystore in that location. SSL

  9. Configure your SSL server-connection channel to use the right cipher spec, they must match on both sides of the communication pipeline.

  10. For the MQ client, place the files in your location of choice and in the configuration UI of the plugin, enter the path to the keystore WITHOUT the .kdb extension. So just type /path/to/SSL/keystore/filename in the SSL Repository field. Also, make sure that the proper cipher spec is selected. SSL

  11. Remember to refresh your SSL config on your Queue Manager to pick up the new SSL changes to your Queue Manager.

Metrics

Queue Manager

  • Availability %
  • Connections
  • Active channels

Channel (split by channel)

  • Channel status
  • Channel messages
  • Bytes sent
  • Bytes received
  • Buffers sent
  • Buffers received
  • Last message
  • Number of conversations

Queues (split by queue)

  • number of messages in queue
  • percent of queue depth
  • Enqueue
  • Dequeue
  • Open in handles
  • Open out handles
  • Oldest message
  • Uncommitted messages
  • Time in queue short period
  • Time in queue long period
  • Last get
  • Last put
  • Inhibit get
  • Inhibit put

Listener (split by listener)

  • Availability %