MQ Channel Plug-In

Introduction

The MQ Channel plug-in is part of a suite of plug-ins designed to monitor an IBM WebSphere MQ server. MQ is a middleware product which allows independent client programs to communicate by passing messages to each other via a message queue. These queues provided added benefits by adding reliability of communications, and storing and persisting messages allowing client programs to operate asynchronously.

The MQ Channel plug-in monitors all configured channels for a particular Queue Manager (an MQ system service which holds a set of queues). Using the Geneos framework administrators can set alerts for events such as a channel going down, or if an unknown process connects on a channel.

MQ Architecture

mq_channel_image2

Websphere MQ servers are based around queues of messages, each Message containing some arbitrary application data. Messages are contained within Queues, which are in turn managed by a Queue Manager. An MQ server may contain several queue managers.

Client applications communicate with each other by sending messages via a queue. To do so they connect to a queue manager - typically using TCP/IP - and send or receive messages accordingly.

Communication between components are handled using pre-configured links called Channels. Channels are mono-directional, so a full-duplex link between two components requires two channels.

A queue manager also has an associated Command Server, which allows a remote client to execute commands. The MQ Channel plug-in connects as a client to the configured queue manager, and obtains monitoring data by issuing status query commands using the command server.

View

MQ Channel produces a single dataview displaying the configured channels for the queue manager it is connected to, and the selected attributes for each view. By default, these attributes include those produced by a DISPLAY CHSTATUS command. An example of this is shown below.

mq_channel_image3

The legends below list all columns which can be configured for this plug-in. For a more in-depth discussion of columns, please see the columns configuration section.

Headline Legend

Name	Description
mqServer	Displays the connection details used to connect to the MQ server.
mqChannelTable	Displays the MQ channel table file used to connect to the MQ server.
queueManager	The name of the queue manager the plug-in is connecting to.
connectionStatus	The current connection status (`UP` or `DOWN`).
samplingStatus	The current status of the plug-in.

Table Legend

Name	Description
name	Name of the channel being monitored.
type	Type of channel, one of `Sender`, `Receiver`, `Server`, `Server Connection`, `Client Connection`, `ClusterSender`, `Cluster Receiver`, `Requester`.
protocol	The transmission protocol used by the channel. One of `Local`, `LU 6.2`, `TCP`, `NetBIOS`, `SPX`, `DECnet`, `UDP`.
status	Status of the connection/channel: For specific connections (only shown when Summary and Detail view is activated), values can be one of `Initializing`, `Binding`, `Starting`, `Running`, `Paused`, `Stopping`, `Retrying`, `Stopped`, `Requesting`. For summary rows of the channel, status depends on the status of the connections within that channel. There are no channel instances: Status shown as `Inactive`. There is a single channel connection: Status shown as the actual status of the connection. There are 2 or more connections, all with the same status: Status shown as the actual status of the connections. There are 2 or more connections, with mixed statuses: Status shown as `Mixed`.
description	A user-configured description of the channel.
connectionName	Connection name. E.g. For a TCP connection, this would be the host and port of the remote queue manager.
remoteQManager	Name of the remote queue manager.
transmitQName	Name of the transmission queue, for a sender channel.
maxMsgLength	Maximum message length which can be sent over this channel, displayed in KB.
alterationDate	Date the channel definition was last altered, in the form `yyyy‑mm‑dd`.
alterationTime	Time the channel definition was last altered, in the form `hh.mm.ss`.
alterationDateTime	A concatenation of the `alterationDate` and `alterationTime` columns showing when the channel definition was last altered, in the form `yyyy‑mm‑dd hh.mm.ss`.
buffersRecv	Number of messages buffers received over the channel.
buffersSent	Number of message buffers sent over the channel.
bytesRecv	Message data in bytes sent over the channel.
bytesSent	Message data in bytes received over the channel.
instanceType	The channel instance type, one of `Current`, `Saved`, `Short`.
startDate	Date the channel was started, in the form `yyyy‑mm‑dd`.
startTime	Time the channel was started, in the form `hh.mm.dd`.
startDateTime	A concatenation of the `startDate` and `startTime` columns showing when the channel was started, in the form `yyyy‑mm‑dd hh.mm.ss`.
heartbeatInterval	The channel heartbeat interval in seconds.
currentLuwid	Current "logical unit of work" identifier, for an in-doubt batch of messages.
currentSeqNo	Sequence number of the last message, for an in-doubt batch of messages.
lastLuwid	The "logical unit of work" identifier for the last committed batch of messages.
lastSeqNo	The sequence number of the last message in the last committed batch of messages.
lastMsgDate	Date the last message was sent, in the form `yyyy‑mm‑dd`.
lastMsgTime	Time the last message was sent, in the form `hh.mm.dd`.
lastMsgDateTime	A concatenation of the `lastMsgDate` and `lastMsgTime` columns showing when the last message was sent, in the form `yyyy‑mm‑dd hh.mm.ss`.
mcaName	Name of the Message Channel Agent (MCA).
mcaUserId	The user id used by the MCA.
mcaStatus	MCA status, either `Stopped` or `Running`.
mcaJobName	Name of the MCA job.
messageCount	Number of messages sent or received.
remoteApp	Remote application name for a server-connection channel, or the remote queue manager / group otherwise.
retriesLeft	Number of short retries left (for reconnections).
stopRequested	Whether a stop request has been registered for this channel. Values are `Yes` or `No`.
sslCipherSpec	SSL cipher specification for the channel.
sslClientAuth	Whether SSL client authentication (a certificate) is required to connect. Values are `Required` or `Optional`.
sslPeerName	Filter to use on the Distinguished Name of the SSL certificate of the peer connecting via the channel.
securityExit	Name of the security exit.
securityUserData	User data passed to the security exit when initiated.

Prerequisites

Before running the MQ Channel plug-in, you must first install the IBM WebSphere MQ Client v7.1 (or greater) software on the machine which the Netprobe will run on. This client comes as part of the MQ software bundle and must be installed correctly - simply copying across the DLLs or shared object files will typically result in a 2012 (MQ environment) error.

On Windows, the mqic.dll library needs to be available to the Netprobe. This is usually done by ensuring that the directory in which this library resides is configured on the PATH environment variable available to the Netprobe.

On Solaris/Linux, the libmqic.so library needs to be available to the Netprobe. This is usually done by ensuring that the directory in which this library resides is configured on the LD_LIBRARY_PATH environment variable available to the Netprobe.

On AIX, the libmqic.a library needs to be available to the Netprobe. This is usually done by ensuring that the directory in which this library resides is configured on the LD_LIBRARY_PATH or LIBPATH environment variable available to the Netprobe.

In order to gather status commands, the MQ command server must be running. Additionally, the Netprobe user must be granted the following permissions to operate, if it is not a member of the mqm administration group:

+connect+dsp permissions on the Queue Manager object
+put+inq permissions on the SYSTEM.ADMIN.COMMAND.QUEUE. If using the send queue parameter, these permissions should be set on the named queue alias instead.
+get+dsp permissions on the SYSTEM.DEFAULT.MODEL.QUEUE. If using the receive queue parameter, the permissions +get +dsp+put+inq should be set on the named queue instead.

In addition certain columns will need additional permissions to be granted on each channel to be monitored as below. The table in thecolumn setting section describes which columns are of which type.

Inquire Channel Status columns require no extra permissions.
Inquire Channel columns require +dsp permissions on each channel.

It is also advisable to enable channel monitoring to gather extra status data, either for the queue manager as a whole or individual channels which are being monitored. This can either be done using WebSphere MQ Explorer, or by issuing the following commands in runmqsc:

alterqmgr monchl(medium) to enable monitoring for all channels on the queue manager with monchl(qmgr) set, or
alterchannel(channelName)chltype(channelType)monchl(medium) to enable monitoring for a specific channel.

Note: If you are using a very short sample interval for your plug-in, it is advised to increase the rate of data collection in MQ from medium to high.

Plug-In Configuration

The following parameters can be configured for this plug-in:

Connection Details

The connection section describes how the MQ Channel plug-in will connect to the MQ server. There are two ways to configure a connection:

Configure an inline connection using the MQSERVER variable.
Configure a connection using a channel table.

If multiple different configuration settings and environment variables exist, MQ Channel will choose a configuration using the following order:

Using the file specified in the mqChannelTable setting.
Using the file specified by the MQCHLLIB and MQCHLTAB environment variables. In this case, variables configured in the managed entity section will be used in preference to those configured in the Netprobe start script.
Using the connection details specified in the mqServer setting.
Using the connection details specified in the MQSERVER environment variable. In this case if the variable is configured in the managed entity section it will be used in preference to a value configured in the Netprobe start script.

If no connection details are supplied, an error message will be produced in the Netprobe log and in the samplingStatus headline of the sampler dataview.

connection

This section contains the connection details used by the MQ Channel plug-in to connect to the MQ server. If not specified, the plug-in will fall back to using the environment variables MQCHLLIB and MQCHLTAB, or if not specified then MQSERVER instead.

These environment variables may be specified either in the managed entity configuration, or in the Netprobe start script.

Mandatory: No

connection > mqServer

The MQ server setting informs the plug-in how to connect to the MQ server. It consists of a channel name, transport type and hostname/port - e.g. CHAN/TCP/testhost(1414)

If set this setting overrides the value of the MQSERVER environment variable. If the mqChannelTable setting has been configured it will be used in preference to this setting.

Please see the IBM documentation for further details on the MQSERVER environment variable.

Mandatory: No

connection > mqChannelTable

The MQ channel table setting allows you to specify the location of a channel table file. This file is created when you define a client-connection channel on your queue manager. MQ clients (including the MQ Channel plug-in in Netprobe) can use the channels within the file to connect to an MQ server.

To configure this setting specify the full path to the channel table. This will then be used over the MQCHLLIB and MQCHLTAB environment variables (if set). It will be also used in preference to the mqServer setting or the MQSERVER environment variable.

Please see the IBM documentation for further details on the MQCHLLIB and MQCHLTAB environment variables.

Mandatory: No

connection > ssl

This sub-section contains details relating to SSL-secured connections to an MQ server.

Note: If using SSL connections it is recommended that all MQ plug-ins running on that Netprobe use the same connection details. The reason for this is that the MQ API only supports a single SSL connection instance per process, and so if using multiple different SSL configurations only the first plug-in will connect successfully.

Mandatory: No

connection > ssl > keyRepository

This setting configures the location of the SSL key repository, which is used when establishing an SSL connection to an MQ server. The key repository contains SSL certificates, and should be created and managed using the IBM key manager utility.

To use this setting specify the full path of the key repository file. It is recommended to exclude the file extension (.kdb) for this value, so that it matches the syntax of the MQSSLKEYR environment variable.

The value of this setting is only required when using SSL connections. These can be specified in two ways:

By configuring the mqServer setting (or MQSERVER environment variable) and also configuring the cipherSpec setting.
By using a channel table (mqChannelTable setting or MQCHLLIB and MQCHLTAB environment variables) which specify an SSL connection.

If specified, this setting will override the value in the MQSSLKEYR environment variable. For more details on this variable, please consult this IBM documentation page.

Mandatory: No

connection > ssl > cipherSpec

This setting is used when the connection is configured using the mqServer setting or the MQSERVER environment variable. If configured, this setting specifies the SSL encryption which will be used to secure the connection, subject to SSL certificate checks.

The value of this setting can either be typed in directly, or selected from the following list of options:

DES_SHA_EXPORT
DES_SHA_EXPORT1024
FIPS_WITH_3DES_EDE_CBC_SHA
FIPS_WITH_DES_CBC_SHA
NULL_MD5
NULL_SHA
RC2_MD5_EXPORT
RC4_56_SHA_EXPORT1024
RC4_MD5_EXPORT
RC4_MD5_US
RC4_SHA_US
TLS_RSA_WITH_3DES_EDE_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_WITH_DES_CBC_SHA
TRIPLE_DES_SHA_US

For more information on cipher specs with MQ, please consult this IBM documentation article.

Mandatory: No

connection > mqSender

This setting allows the user to specify the name of the queue to send commands on, for execution by the command server. If not specified, the plug-in will send requests for monitoring data (commands) using the default name SYSTEM.ADMIN.COMMAND.QUEUE.

In practise this setting need not be defined unless the MQ server has been configured with a non-default command queue name.

Mandatory: No

Default: SYSTEM.ADMIN.COMMAND.QUEUE

connection > mqReceiver

This setting allows the user to specify the name of a (permanent) queue to receive command results (monitoring data) from, following execution by the command server. If not specified the plug-in will use the default behaviour of the IBM MQAI library, which is to create a new dynamic queue for the reply (based on the SYSTEM.DEFAULT.MODEL.QUEUE) which is automatically deleted after use.

Users may wish to configure this setting if they are having problems with command results being placed on the dead letter queue. These "dead" messages contain stale monitoring data and so are safe to delete, but their creation can be avoided by use of a permanent reply queue. Use of a permanent reply queue can avoid also the (small) cost of creation/deletion of a dynamic reply queue.

When using a permanent queue only a single queue per MQ server instance is required (although you may use additional queues as required). The Netprobe user will require a minimum of +get+dsp +put+inq permissions on the queue to operate correctly. The queue can safely be shared by multiple MQ plug-in instances (either running on the same or different Netprobes) as each MQ plug-in will obtain its own monitoring data from the queue using a correlation id. The depth of the permanent queue should remain at (or close to) 0. Any messages on the queue older than a few minutes may be safely deleted.

Mandatory: No

connection > securityExitConfig > securityExit

This setting allows the user to specify a client side security exit to use when authenticating with the MQ server. See the IBM documentation for the SecurityExit field on the MQCD structure for more information.

Note: This configuration will only work with MQServer. If a channel table is used in the configuration then the settings here will be ignored.

Mandatory: No

connection > securityExitConfig > remoteUserIdentifier

This setting allows the user to specify the Remote User Identifier that will be sent to the client side security exit and the server when authenticating. Only the first 12 characters will be used, see the IBM documentation for the RemoteUserIdentifier field on the MQCD structure for more information.

Mandatory: No

connection > securityExitConfig > remotePassword

This setting allows the user to specify the Remote Password that will be sent to the client side security exit and the server when authenticating. Only the first 12 characters will be used, see the IBM documentation for the RemotePassword field on the MQCD structure for more information.

Mandatory: No

connection > securityConnectionAuthenticationConfig > username

This setting allows the user to specify a username in order to connect to the MQ server which supports Security Connection Authentication. The username provided does not need to be part of the mqm group. But keep in mind that the user running the Netprobe should have been given the default MQ user permissions. This includes having the user added to the mqm group, authorised to connect to the Queue manager, channel, and queue. As the netprobe user would be the one used for MQ authorisation checks. But if ADOPTCTX attribute is set to YES then the Connection Authentication username provided would be used instead throughout the connection. See the IBM documentation on MQCSP password protection and on Connection Authentication: Configuration for more information.

Note: The Security Connection Authentication is applicable only to IBM MQ Version 8.0. If the version is lower than 8.0 then this configuration will have no bearing.

Mandatory: No

connection > securityConnectionAuthenticationConfig > password

This setting allows the user to specify the password for the given username that will connect to the MQ server which supports Security Connection Authentication. See the IBM documentation on MQCSP password protection and on Connection Authentication: Configuration for more information.

Mandatory: No

Channels

By default, MQ Channel will monitor all channels on the configured queue manager. The channels section allows users to configure only the channels they are interested in for monitoring.

queueManager

This setting specifies the name of the queue manager the plug-in is to connect to. If a channel table is used, then this name should match the one specified for the connection.

Mandatory: Yes

channels

The channels section specifies the channels that will be monitored by the plug-in. By default, if no channels are specified then all channels on the queue manager will be monitored.

Mandatory: No

channels > channel

Specifies a channel (or channels for a generic name) for the MQ Channel plug-in to monitor. If no channels are specified all channels on the queue manager will be monitored.

Mandatory: No

channels > channel > matches

This setting specifies the exact name of a channel to monitor.

Mandatory: No

channels > channel > startsWith

This setting specifies a prefix of a channel name. All channels on the queue manager starting with the prefix will be monitored.

The startsWith setting uses the generic queue names feature of the command server. For example, if you entered the value SYSTEM then the monitored channels would be the same as the channels returned when you issue the command DISPLAY CHSTATUS(SYSTEM*) using the runmqsc MQ utility. You may also add the trailing * in the setting value if you wish to match the standard MQ syntax.

Mandatory: No

Columns

By default, MQ Channel will display columns including the data you would see when executing the DISPLAYCHSTATUS command in the runmqsc MQ utility, along with some additional metrics (see below for more details). The columns section allows users to configure a set of columns that they wish to see, and ignore data which is not relevant for their particular monitoring configuration.

columns

The columns section specifies the columns which will be produced by the MQ Channel plug-in. Columns appear in the order in which they are configured. The name column is always present as the first column. If no columns are specified, then a default set of columns displaying most of the output from the DISPLAYCHSTATUS command is used.

Mandatory: No

columns > column

The column setting configures a single column which will be displayed in the resulting dataview. For a description of what each column shows, please see the view section table legend.

Columns will be added to the dataview in the order they have been configured. If a column has already been added, then a duplicate entry will be ignored.

Column data for MQ Channel comes from executing inquire channel and inquire channel status commands using the command server on the MQ queue manager. Columns which obtain data from a channel status command may appear blank unless channel monitoring is enabled - see the prerequisites section for details on how to do this.

The following table shows which command is run to obtain data for each column. The default columns (which are displayed if no other columns are configured) are also displayed.

Column	Default	Inq. Channel	Inq. Channel Status
type	X	X	X
protocol	X	X
status	X		X
description	X	X
connectionName	X	X	X
remoteQManager	X		X
transmitQName	X	X	X
maxMsgLength	X	X
alterationDate		X
alterationTime		X
alterationDateTime		X
buffersRecv			X
buffersSent			X
bytesRecv	X		X
bytesSent	X		X
instanceType			X
startDate			X
startTime			X
startDateTime			X
heartbeatInterval			X
currentLuwid			X
currentSeqNo			X
lastLuwid			X
lastSeqNo			X
lastMsgDate			X
lastMsgTime			X
lastMsgDateTime			X
mcaName		X
mcaUserId		X	X
mcaStatus	X		X
mcaJobName			X
messageCount	X		X
remoteApp			X
retriesLeft			X
stopRequested			X
sslCipherSpec		X
sslClientAuth		X
sslPeerName		X
securityExit		X
securityUserData		X

Further descriptions of these attributes can be found at the following IBM documentation pages:

Additional options

displayFormat

The display format setting controls whether details rows are displayed in the dataview output. Details rows are shown as an indented set of (sub-)rows under a (summary) channel row. These sub-rows show statistics for each individual connection using a channel. The sub rows are identified by the MCA Job Name. The summary rows show totalled statistics for the whole channel.

Possible values for this setting are:

Setting	Meaning
SummaryOnly	Only the summary rows are displayed, showing the totalled statistics for that whole channel.
SummaryAndDetails	The summary rows are displayed along with the detail rows. Each detail row shows statistics for a single connection using that channel.

Mandatory: No

Default: Summary Only

Debug

The debug section contains settings used for debugging purposes. You may be asked to configure these by ITRS support if you are having issues with the MQ Channel plug-in, in order to diagnose the problem.

debug

The debug section contains debugging settings for the MQ Channel plug-in. Typically users should not need to configure any setting in this section.

Mandatory: No

debug > sampleTimeout

The sample timeout controls the number of seconds MQ Queue will spend during a sample, before it gives up and displays any data obtained so far. This setting typically only comes into effect if the MQ server is slow to respond to queries, which may happen during times of heavy load.

Mandatory: No

Default: Half the Netprobe heartbeat interval (approx 35 seconds), with a minimum of 20s.

debug > output

The debug output settings enable additional output which is sent to the Netprobe log file.

Mandatory: No

debug > output > setup

If enabled, this Boolean setting produces output regarding the results of the sampler setup parsing.

Mandatory: No

Default: false

debug > output > mqApi

If enabled, this Boolean setting produces output regarding the results of all MQ API calls made by the plug-in.

Mandatory: No

Default: false

debug > output > connection

If enabled, this Boolean setting produces output regarding connection attempts, successes and failures to aid in debugging connection issues.

Mandatory: No

Default: false

debug > output > commands

If enabled, this Boolean setting produces output regarding commands being executed by the plug-in.

Mandatory: No

Default: false

debug > output > results

If enabled, this Boolean setting produces output regarding the results processing of a successful command execution.

Mandatory: No

Default: false

MQ Connection Backoff

This section describes the mechanism to prevent MQ connections after a certain number of consecutive failures.

By default, MQ plugins will continually attempt connections to the MQ server, even after connections have continually failed. To prevent this, connectionFailureThreshold and connectionFailureStopTime can be configured to manage MQ connection backoff. These configurations are located under the Probe configuration's advanced tab (refer to Gateway2 Reference Guide). Setting these configurations will put into place a mechanism which will prevent MQ connections from being attempted after a given number of failures.

The connectionFailureThreshold is the maximum number of failures that can be allowed before initiating an MQ connection backoff. Once a backoff has been started, the netprobe will try to reconnect only after the indicated connectionFailureStopTime in seconds has been reached. If reconnection is successful, MQ connections will work normally. If reconnection is unsuccessful, backoff for the indicated time in connectionFailureStopTime will be once again put into effect.

These configurations are shared across several MQ plugins using the same connection in the same probe. This means that the count for consecutive failures will be counted against each unique MQ connection and not in each sampler.

XML Examples

Minimal setup

This example shows the bare minimum configuration for MQ Channel. This example assumes that connection details for the MQ server are configured as environment variables. As no channels and columns have been specified, all channels on the queue manager will be monitored for the default set of statistics.

<sampler name="minChannelExample">
        <plugin>
                <mq-channel>
                        <queueManager>
                                <data>QM.test.sim</data>
                        </queueManager>
                        <connection>
                                <mqServer>
                                        <data>CH.TEST/TCP/itrs-mq6(1416)</data>
                                </mqServer>
                        </connection>
                </mq-channel>
        </plugin>
</sampler>

SSL connection using MQSERVER setting

The following example shows how to configure MQ Channel to connect using an SSL connection in conjunction with the MQSERVER variable. This is done by specifying an SSL cipher for encryption, and the location of the SSL certificate key repository.

The example also shows a configuration for channels, selecting all channels starting SEND, RECV, and the specific channel named CH.TEST.

<sampler name="channelMQServerWithSSL">
        <plugin>
                <mq-channel>
                        <queueManager>
                                <data>QM.test.sim</data>
                        </queueManager>
                        <connection>
                                <mqServer>
                                        <data>CH.TEST/TCP/itrs-mq6(1416)</data>
                                </mqServer>
                                <ssl>
                                        <keyRepository>
<data>C:\Program Files\IBM\WebSphere MQ\ssl\key</data>
                                        </keyRepository>
                                        <cipherSpec><data>TRIPLE_DES_SHA_US</data></cipherSpec>
                                </ssl>
                        </connection>
                        <channels>
                                <channel>
                                        <startsWith><data>SEND</data></startsWith>
                                </channel>
                                <channel>
                                        <startsWith><data>RECV</data></startsWith>
                                </channel>
                                <channel>
                                        <matches><data>CH.TEST</data></matches>
                                </channel>
                        </channels>
                </Mmq-channel>
        </plugin>
</sampler>

Channel table file connection

This example shows how to configure MQ Channel to use a channel table file. This file should define a client-connection which MQ Channel will use to connect to the queue manager. If this channel also has SSL settings configured, then you will need to specify the location of the key repository in order to successfully authenticate. Additionally, any security exit configuration in the sampler will be ignored.

The example also shows the use of the columns setting to select a set of columns for display, and also a debug setting which produces output of the MQ API calls being made.

<sampler name="channelTableFile">
<plugin>
        <mq-channel>
                <queueManager>
                        <data>QM.test.sim</data>
                </queueManager>
                <connection>
                        <mqChannelTable>
                                <data>C:\Program Files\IBM\WebSphere MQ\AMQCLCHL.TAB</data>
                        </mqChannelTable>
                </connection>
                <columns>
                        <column>protocol</column>
                        <column>type</column>
                        <column>status</column>
                        <column>mcaStatus</column>
                        <column>mcaJobName</column>
                        <column>remoteApp</column>
                        <column>sslCipherSpec</column>
                        <column>sslClientAuth</column>
                        <column>securityExit</column>
                        <column>securityUserData</column>
                </columns>
                <debug>
                        <output>
                                <mqApi>true</mqApi>
                        </output>
                </debug>
        </mq-channel>
</plugin>
</sampler>