Configuring a queue manager for telemetry on Linux and AIX®

Follow these manual steps to configure a queue manager to run IBM® MQ Telemetry. You can run an automated procedure to set up a simpler configuration using the IBM MQ Telemetry support for MQ Explorer.

Before you begin

  1. See Installing IBM MQ Telemetry for information on how to install IBM MQ and the IBM MQ Telemetry feature.
  2. Create and start a queue manager. The queue manager is referred to as qMgr in this task.
  3. As part of this task you configure the telemetry (MQXR) service. The MQXR property settings are stored in a platform-specific properties file: mqxr_unix.properties. You do not normally need to edit the MQXR properties file directly, because almost all settings can be configured through MQSC admin commands or MQ Explorer. If you do decide to edit the file directly, stop the queue manager before you make your changes. See MQXR properties.

About this task

The IBM MQ Telemetry support for MQ Explorer includes a wizard, and a sample command procedure sampleMQM. They set up an initial configuration using the guest user ID; see Verifying the installation of IBM MQ Telemetry by using MQ Explorer and IBM MQ Telemetry Transport sample programs.

Follow the steps in this task to configure IBM MQ Telemetry manually using different authorization schemes.

Procedure

  1. Open a command window at the telemetry samples directory.

    The telemetry samples directory is /opt/mqm/mqxr/samples.

  2. Create the telemetry transmission queue. 
    
echo "DEFINE QLOCAL('SYSTEM.MQTT.TRANSMIT.QUEUE') USAGE(XMITQ) MAXDEPTH(100000)" | runmqsc qMgr

    When the telemetry (MQXR) service is first started, it creates SYSTEM.MQTT.TRANSMIT.QUEUE.

    It is created manually in this task, because SYSTEM.MQTT.TRANSMIT.QUEUE must exist before the telemetry (MQXR) service is started, to authorize access to it.

  3. Set the default transmission queue

    When the telemetry (MQXR) service is first started, it does not alter the queue manager to make SYSTEM.MQTT.TRANSMIT.QUEUE the default transmission queue.

    To make SYSTEM.MQTT.TRANSMIT.QUEUE the default transmission queue alter the default transmission queue property. Alter the property using the MQ Explorer or with the command in the following example: 
    
echo "ALTER QMGR DEFXMITQ('SYSTEM.MQTT.TRANSMIT.QUEUE')" | runmqsc qMgr

    Altering the default transmission queue might interfere with your existing configuration. The reason for altering the default transmission queue to SYSTEM.MQTT.TRANSMIT.QUEUE is to make sending messages directly to MQTT clients easier. Without altering the default transmission queue you must add a remote queue definition for every client that receives MQ Explorer messages; see Sending a message to a client directly.

  4. Follow a procedure in Authorizing MQTT clients to access IBM MQ objects to create one or more user IDs. The user IDs have the authority to publish, subscribe, and send publications to MQTT clients.
  5. Install the telemetry (MQXR) service 
    
cat /opt/<install_dir>/mqxr/samples/installMQXRService_unix.mqsc | runmqsc qMgr

    See also the example code in Figure 1.

  6. Start the service 
    
echo "START SERVICE(SYSTEM.MQXR.SERVICE)" | runmqsc qMgr

    The telemetry (MQXR) service is started automatically when the queue manager is started.

    It is started manually in this task, because the queue manager is already running.

  7. Using MQ Explorer, configure telemetry channels to accept connections from MQTT clients.

    The telemetry channels must be configured such that their identities are one of the user IDs defined in step 4.

    See also DEFINE CHANNEL (MQTT).

  8. Verify the configuration by running the sample client.

    For the sample client to work with your telemetry channel, the channel must authorize the client to publish, subscribe, and receive publications. The sample client connects to the telemetry channel on port 1883 by default. See also IBM MQ Telemetry Transport sample programs.

Example

Figure 1 shows the runmqsc command to create the SYSTEM.MQXR.SERVICE manually on Linux®.
Figure 1. installMQXRService_unix.mqsc

DEF	SERVICE(SYSTEM.MQXR.SERVICE) +
CONTROL(QMGR) +
DESCR('Manages clients using MQXR protocols such as MQTT') +
SERVTYPE(SERVER) +
STARTCMD('+MQ_INSTALL_PATH+/mqxr/bin/runMQXRService.sh') +
STARTARG('-m +QMNAME+ -d "+MQ_Q_MGR_DATA_PATH+" -g "+MQ_DATA_PATH+"') +
STOPCMD('+MQ_INSTALL_PATH+/mqxr/bin/endMQXRService.sh') +
STOPARG('-m +QMNAME+') +
STDOUT('+MQ_Q_MGR_DATA_PATH+/mqxr.stdout') +
STDERR('+MQ_Q_MGR_DATA_PATH+/mqxr.stderr')