Setting up a remote queue manager to use with the messaging REST API

You can use the messaging REST API to connect to remote queue managers for messaging. Before you can connect to a remote queue manager, you must set up the remote queue manager configuration. Then, you can connect to the remote queue manager by using the unique name that is defined in the configuration information.

1. On the remote queue manager, create a server-connection channel to allow remote connections to the queue manager. You can create server-connection channels by using the DEFINE CHANNEL MQSC command on the command line.
   For example, to create a server-connection channel QM1.SVRCONN for queue manager QM1, enter the following command:

   DEFINE CHANNEL(QM1.SVRCONN) CHLTYPE(SVRCONN) TRPTYPE(TCP)

   For more information about DEFINE CHANNEL and the options available, see DEFINE CHANNEL.
2. Ensure that an appropriate user is authorized to access the queue manager. The user needs connect, inquire, alternate user, and set context authority on the queue manager. On UNIX, Linux®, and Windows use the setmqaut control command on the command line. On z/OS®, define RACF profiles to give the authorized user access to the queue manager.
   For example, on UNIX, Linux, and Windows, to authorize a user, exampleUser, to access the queue manager QM1, enter the following command:

   setmqaut -m QM1 -t qmgr -p exampleUser +connect +inq +altusr +setall

3. Grant the user set context authority on any queues or topics that you use for messaging, using the setmqaut control command on UNIX, Linux, and Windows, and RACF on z/OS.
   For example, on UNIX, Linux, and Windows, if the queue EXAMPLEQ is being used for messaging, enter the following command to give exampleUser set context authority:

   setmqaut -m QM1 -t queue -p exampleUser -n EXAMPLEQ +setall

4. If mqRestMessagingAdoptWebUserContext is or will be set to false in the mqweb server configuration, the user defined in step 2 must also be authorized to access the queues and topics that you will use for messaging. If mqRestMessagingAdoptWebUserContext is or will be set to true, the users that have the MQWebUser role must be authorized to access queues and topics that are used for messaging. On UNIX, Linux, and Windows, this can be done using the setmqaut command. On z/OS, use RACF profiles to give the users the correct authority.
   For more information about which user needs to be authorized, see Determining the security principal used by the messaging REST API.
5. If no listener exists on the remote queue manager, create a listener to accept incoming network connections by using the DEFINE LISTENER MQSC command on the command line.
   For example, to create a listener REMOTE.LISTENER on port 1414 for remote queue manager QM1, enter the following command:

   runmqsc QM1
   DEFINE LISTENER(REMOTE.LISTENER) TRPTYPE(TCP) PORT(1414)
   end

6. Ensure that the listener is running by using the START LISTENER MQSC command on the command line:
   For example, on AIX®, Linux, and Windows to start the listener REMOTE.LISTENER for queue manager QM1, enter the following command:

   runmqsc QM1
   START LISTENER(REMOTE.LISTENER)
   end

   For example, on z/OS, to start the listener, enter the following command:

   runmqsc QM1
   START LISTENER TRPTYPE(TCP) PORT(1414)
   end

   The channel initiator address space must be started before you can start a listener on z/OS.
7. On the system where the mqweb server that hosts the messaging REST API is running, create or update a JSON CCDT file that contains the queue manager connection information.

   The CCDT file must include the name, clientConnection, and type information. You can optionally include additional information such as transmissionSecurity information. For more information about all the CCDT channel attribute definitions, see Complete list of CCDT channel attribute definitions.

   The following example shows a basic JSON CCDT file for a remote queue manager connection. It sets the name of the channel to the same name as the example server-connection channel created in step 1. The connection port is set to the same value as the port that is used by the listener. The connection host is set to the hostname of the system on which the remote queue manager, QM1, is running.

   {
     "channel": [{
         "name": "QM1.SVRCONN",
         "clientConnection": {
           "connection": [{
               "host": "example.com",
               "port": 1414
             }],
           "queueManager": "QM1"
         },
         "type": "clientConnection"
       }]
   }

8. From the installation that is running the mqweb server that hosts the messaging REST API, use the setmqweb remote command to add the remote queue manager information to the mqweb server configuration.
   As a minimum, you must specify the following parameters:

   • -qmgrName, where you specify the name of the queue manager.
   • -ccdtURL, where you specify the CCDT URL for the queue manager.
   • -uniqueName, where you specify a unique name for the queue manager. The unique name is used to differentiate remote queue managers that might have the same name, and therefore must not exist to identify another queue manager.

   You can specify several other options, such as the username and password to use for the remote queue manager connection, or details of the truststore and keystore. For a full list of parameters that can be specified with the setmqweb remote command, see setmqweb remote.

   For example, to add the remote queue manager QM1, with the example CCDT file, enter the following command:

   setmqweb remote add -uniqueName "RemoteQM1" -qmgrName "QM1" -ccdtURL "c:\myccdts\ccdt.json"