[AIX][Linux]

Configuring a queue manager for telemetry on Linux® and AIX®

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

Before you begin

If you only need a simple configuration, consider using the IBM 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 IBM MQ Telemetry by using IBM MQ Explorer and 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:
  1. See Installation considerations for 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_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 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.

    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 IBM 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
  3. 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
  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. Edit the installMQXRService_unix.mqsc file to configure the key file that is used to encrypt passphrase for MQTT TLS channels:
    1. Open the WMQ program installation directory/mqxr/samples/installMQXRService_unix.mqsc file.
    2. Locate the line that includes the STARTARGparameter and edit the -sf option to specify the location of your credentials key file.
      By default, the installMQXRService_unix.mqsc file uses a default key file named [DEFAULT]. The default key file is the same for all IBM MQ installations, so you must supply a key file that is unique to your installation when you encrypt passphrases.

      See also the example code in Creating the SYSTEM.MQXR.SERVICE.

  6. Install the telemetry (MQXR) service by running the following command: 
    cat /opt/<install_dir>/mqxr/samples/installMQXRService_unix.mqsc | runmqsc queue_manager
  7. 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.

  8. 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).

  9. 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 MQ Telemetry Transport sample programs.

Creating the 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.sh') +
STARTARG('-m +QMNAME+ -d "+MQ_Q_MGR_DATA_PATH+" -g "+MQ_DATA_PATH+" -sf "/home/keyFileLocation/keyFile.txt"') +
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')