Remote administration using the REST API

You can use the REST API to administer remote queue managers, and the IBM® MQ objects that are associated with those queue managers. This remote administration includes queue managers that are on the same system, but not in the same IBM MQ installation as the mqweb server. Therefore, you can use the REST API to administer your entire IBM MQ network with only one installation that runs the mqweb server. To administer remote queue managers, you must configure the administrative REST API gateway so that at least one queue manager in the same installation as the mqweb server acts as a gateway queue manager. Then, you can specify the remote queue manager in the REST API resource URL to perform the specified administrative action.

1. Configure communications between the gateway queue manager and the remote queue managers that you want to administer. These configuration steps are the same steps that are required to configure remote administration by runmqsc and PCF.
   For more information about these steps, see Remote administration from a local queue manager.
2. Configure security on the remote queue managers:
   1. Ensure that the relevant user IDs exist on the system that the remote queue manager runs on. The user ID that must exist on the remote system depends on the role of the REST API user:
      • If the REST API user is in the MQWebAdmin or the MQWebAdminRO group, the user ID that started the mqweb server must exist on the remote system. On the IBM MQ Appliance, the user that starts the mqweb server is mqsystem.
      • If the REST API user is in the MQWebUser group, that REST API user ID must exist on the remote system.
   2. Ensure that the relevant user IDs are granted the necessary levels of authority to access the appropriate REST API resources on the remote queue manager:
      • Authority to put messages to the SYSTEM.ADMIN.COMMAND.QUEUE.
      • Authority to put messages to the SYSTEM.REST.REPLY.QUEUE.
      • Authority to access the transmissions queues that are defined for remote administration.
      • Authority to display queue manager attributes.
      • Authority to perform the REST requests. For more information, see the Security requirements section of the REST API resources reference topics.
3. Configure which local queue manager is used as the gateway. You can configure a default gateway queue manager, specify the gateway queue manager in an HTTP header, or use a combination of both approaches:
   • Configure a default gateway queue manager by using the setmqweb command:

     setmqweb properties -k mqRestGatewayQmgr -v qmgrName

     where qmgrName is the name of the gateway queue manager.

     This gateway queue manager is used when both the following statements are true:

     • A queue manager is not specified in the ibm-mq-rest-gateway-qmgr header of a REST request.
     • The queue manager that is specified in the REST API resource URL is not a local queue manager.
   • Configure the gateway queue manager on every REST request by setting the HTTP header ibm-mq-rest-gateway-qmgr to the name of the gateway queue manager.
4. Include the name of the remote queue manager that you want to administer in the resource URL.
   For example, to get a list of queues from the remote queue manager remoteQM, use the following URL:

   https://localhost:9443/ibmmq/rest/v1/admin/qmgr/remoteQM/queue

Example

In the following example, there are three IBM MQ installations on two machines. On Machine 1, there is an Installation 1 and an Installation 2. On Machine 2, there is an Installation 3. An mqweb server is configured for Installation 1. There is a single queue manager in each installation, and these queue managers are configured for remote administration. That is, the following listeners, channels and queues are configured and started:

• On queue manager QM1, in Installation 1, on Machine 1:
  • Sender channel QM1.to.QM2
  • Receiver channel QM2.to.QM1
  • Sender channel QM1.to.QM3
  • Receiver channel QM3.to.QM1
  • Transmission queue QM2
  • Transmission queue QM3
  • A listener configured on port 1414
• On queue manager QM2, in Installation 2, on Machine 1:
  • Sender channel QM2.to.QM1
  • Receiver channel QM1.to.QM2
  • Transmission queue QM1
  • A listener configured on port 1415
• On queue manager QM3, in Installation 3, on Machine 2:
  • Sender channel QM3.to.QM1
  • Receiver channel QM1.to.QM3
  • Transmission queue QM1
  • The default listener

A queue, Qon2 is defined on QM2, and a queue Qon3 is defined on QM3.

The user mquser is defined on both machines, is granted the MQWebAdmin role in the REST API, and is granted authority to access the appropriate queues on each queue manager.

The setmqweb command is used to configure queue manager QM1 as the default gateway queue manager.

The following diagram shows this configuration:

The following REST request is sent to the mqweb server:

GET https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM2/queue?attributes=general.isTransmissionQueue

The following response is received:

{
   "queue" :
   [{
        "general": {
            "isTransmissionQueue": true
        },
        "name": "QM1",
        "type": "local"
    },
   {
        "general": {
            "isTransmissionQueue": false
        },
        "name" : "Qon2",
        "type" : "local"
    }]
}

The following REST request is sent to the mqweb server:

GET https://localhost:9443/ibmmq/rest/v1/admin/qmgr/QM3/queue?attributes=general.isTransmissionQueue,general.description

The following response is received:

{
   "queue" :
   [{
        "general": {
            "isTransmissionQueue": true,
            "description": "Transmission queue for remote admin."
        },
        "name": "QM1",
        "type": "local"
    },
   {
        "general": {
            "isTransmissionQueue": false,
            "description": "A queue on QM3."
        },
        "name" : "Qon3",
        "type" : "local"
    }]
}