Configuring the MQTT service from the command line

Follow these instructions configure IBM® WebSphere® MQ using the command line to run the sample IBM WebSphere MQ Telemetry applications. The steps show you how to run a script to create an MQTT service on a new queue manager called MQXR_SAMPLE_QM.

Before you begin

You must have administrative access to a IBM WebSphere MQ queue manager to set up the MQTT service. You have a number of ways to get access to a queue manager:

Get a copy of IBM WebSphere MQ and create a queue manager on your own Linux® or Windows workstation. Follow the instructions in Installing IBM WebSphere MQ to obtain and install IBM WebSphere MQ. Note that you need to also select Telemetry Service and Telemetry Clients when installing. You can also modify an existing installation to add these options.
Contact an IBM WebSphere MQ administrator and ask for administrative access to a queue manager on a server that has IBM WebSphere MQ Telemetry installed as an option. In addition to the name of the queue manager, you require at least two TCP/IP ports for MQTT and for MQTT over WebSockets. If you are planning to connect secure clients, you require at least two more ports.

To do the steps in the task exactly as they are described, you must be able to create a queue manager called MQXR_SAMPLE_QM, and TCP/IP port 1883 must be unused.

About this task

In this task you run a script that creates a queue manager, and then configures the MQTT service to listen for MQTT V3.1 client connections on port 1883. The configuration gives everyone permission to publish and subscribe to any topic. The configuration of security and access control is minimal and is intended only for a queue manager that is on a secure network with restricted access. To run IBM WebSphere MQ and MQTT in an insecure environment, you must configure security. To configure security for IBM WebSphere MQ and MQTT, see the related links at the end of this task.

Procedure

Log on with a user ID that has administrative authority to IBM WebSphere MQ.
To define a user ID with administrative authority to IBM WebSphere MQ, see step 3 in Installing IBM WebSphere MQ.
Open a command window and run the sample command script to create and start the sample queue manager called MQXR_SAMPLE_QM and the MQTT service.
The path to the sample script is %MQ_FILE_PATH%\mqxr\samples\SampleMQM.bat on Windows and MQ_INSTALLATION_PATH/mqxr/samples/SampleMQM.sh on Linux.

Type the following command to create and configure the queue manager:
- ```
"%MQ_FILE_PATH%\mqxr\samples\SampleMQM.bat"
```
- ```
MQ_INSTALLATION_PATH/mqxr/samples/SampleMQM.sh
```

Results

The sample creates an MQTT channel called PlainText with these properties on Windows:

com.ibm.mq.MQXR.channel/PlainText: \
com.ibm.mq.MQXR.Protocol=MQTT;\
com.ibm.mq.MQXR.Port=1883;\
com.ibm.mq.MQXR.Backlog=4096;\
com.ibm.mq.MQXR.UserName=Guest;\
com.ibm.mq.MQXR.StartWithMQXRService=true

The channel properties on Linux are the same as Windows, except com.ibm.mq.MQXR.UserName=nobody.

MQTT V3.1 clients that connect to port 1883 access IBM WebSphere MQ with the user ID set in the variable com.ibm.mq.MQXR.UserName. The sample script authorizes the user ID with the following IBM WebSphere MQ commands:

setmqaut -m MQXR_SAMPLE_QM -t topic -n SYSTEM.BASE.TOPIC -p com.ibm.mq.MQXR.UserName -all +pub +sub
setmqaut -m MQXR_SAMPLE_QM -t q -n SYSTEM.MQTT.TRANSMIT.QUEUE -p com.ibm.mq.MQXR.UserName -all +put

The first command gives the user authority to publish and subscribe on topics that inherit their permissions from the base topic. The second command gives the user authority to put messages on the SYSTEM.MQTT.TRANSMIT.QUEUE transmission queue. The MQTT service sends messages on the SYSTEM.MQTT.TRANSMIT.QUEUE as publications to MQTT subscribers.

The script starts the MQTT service on the queue manage to listen for connections on port 1883.

What to do next

Follow these steps to test the connection by running the sample MQTT V3.1 Java application.

The source for the sample Java application is in the MQTTV3Sample.java file.

Two command windows are required to run the sample. Run the sample as a subscriber in one window and as publisher in the other.

To start the subscriber, run the command

"%MQ_FILE_PATH%\mqxr\samples\RunMQTTV3Sample.bat" -a subscriber

To publish, run the command:

"%MQ_FILE_PATH%\mqxr\samples\RunMQTTV3Sample.bat"

To start the subscriber, run the command

MQ_INSTALLATION_PATH/mqxr/samples/RunMQTTV3Sample.sh -a subscriber

To publish, run the command:

MQ_INSTALLATION_PATH/mqxr/samples/RunMQTTV3Sample.sh

The publisher and subscriber write output to their command windows:

Output from the sample publisher — Figure 1. Output from the publisher

Output from the sample subscriber — Figure 2. Output from the subscriber

The server is now ready for you to test your MQTT V3.1 app.