Configuring a queue manager for telemetry on Windows

Follow these steps to configure MQ Telemetry manually. If you only need a simple configuration that uses the guest user ID, you can instead run the MQ Telemetry support wizard in IBM® MQ Explorer.

Before you begin

If you only need a simple configuration, consider using the MQ Telemetry support in IBM MQ Explorer. This support includes a wizard and a sample command procedure sampleMQM. These resources set up an initial configuration using the guest user ID. See Verifying the installation of MQ Telemetry by using IBM MQ Explorer and IBM MQ Telemetry Transport sample programs.

If you need a more complex configuration that uses a different authentication method, use the steps in this task. Begin with the following initial steps:

See Installation considerations for MQ Telemetry for information on how to install IBM MQ, and the MQ Telemetry feature.
Create and start a queue manager. The queue manager is referred to as qMgr in this task.
As part of this task you configure the telemetry (MQXR) service. The MQXR property settings are stored in a platform-specific properties file: mqxr_win.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 IBM 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

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

Procedure

Open a command window at the telemetry samples directory.

The telemetry samples directory is WMQ program installation directory\mqxr\samples.
Create the telemetry transmission queue.

If SYSTEM.MQTT.TRANSMIT.QUEUE does not exist, it is created automatically when the telemetry (MQXR) service is first started, and set to use the guest user ID. However this task configures MQ Telemetry to use a different authorization scheme. For this task, you create SYSTEM.MQTT.TRANSMIT.QUEUE, and configure access to it, before you start the telemetry (MQXR) service.
Run the following command:
```
echo DEFINE QLOCAL('SYSTEM.MQTT.TRANSMIT.QUEUE') USAGE(XMITQ) MAXDEPTH(100000) | runmqsc qMgr
```
Set the default transmission queue.

It is easier to send messages directly to MQTT clients if SYSTEM.MQTT.TRANSMIT.QUEUE is the default transmission queue. Otherwise, you have to add a remote queue definition for every client that receives IBM MQ messages; see Sending a message to a client directly. Note that altering the default transmission queue might interfere with your existing configuration.

When the telemetry (MQXR) service is first started, it does not set SYSTEM.MQTT.TRANSMIT.QUEUE as the default transmission queue for the queue manager. To configure this setting, you alter the default transmission queue property. You do this either by using the IBM MQ Explorer, or by running the following command:
```
echo ALTER QMGR DEFXMITQ('SYSTEM.MQTT.TRANSMIT.QUEUE') | runmqsc qMgr
```
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.
Install the telemetry (MQXR) service.
```
type installMQXRService_win.mqsc | runmqsc qMgr
```
See also the example code in Creating SYSTEM.MQXR.SERVICE.
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.
Using IBM 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).
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.

Creating `SYSTEM.MQXR.SERVICE`

Use the runMQXRService command to create the SYSTEM.MQXR.SERVICE.


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.bat') +
STARTARG('-m +QMNAME+ -d "+MQ_Q_MGR_DATA_PATH+\." -g "+MQ_DATA_PATH+\." -sf "[DEFAULT]"') +
STOPCMD('+MQ_INSTALL_PATH+\mqxr\bin\endMQXRService.bat') +
STOPARG('-m +QMNAME+') +
STDOUT('+MQ_Q_MGR_DATA_PATH+\mqxr.stdout') +
STDERR('+MQ_Q_MGR_DATA_PATH+\mqxr.stderr')

Note: From IBM MQ 9.2.4 onwards, the -sf flag provides the credentials key file name that contains the key to be used to encrypt TLS channel passphrases. For more information, see Encryption of passphrases for MQTT TLS channels.