Remote administration using the REST API

We 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, we 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, we can specify the remote queue manager in the REST API resource URL to perform the specified administrative action.


Before starting

We can prevent remote administration by disabling the administrative REST API gateway. For more information, see Configure the administrative REST API gateway.

To use the administrative REST API gateway, the following conditions must be met:

  • The mqweb server must be configured and started. For more information about configuring and starting the mqweb server, see Getting started with the administrative REST API.
  • The queue manager that we want to configure as the gateway queue manager must be in the same installation as the mqweb server.
  • The remote queue manager that we want to administer must be at Version 8.0 or later.
  • We must ensure that any attributes that are specified in your request are valid for the system that we are sending the request to. For example, if the gateway queue manager is on Windows and the remote queue manager is on z/OS, we cannot request that the dataCollection.statistics attribute is returned for an HTTP GET request on the queue resource.
  • We must ensure that any attributes that are specified in your request are valid for the level of IBM MQ that we are sending the request to. For example, if the remote queue manager is running IBM MQ Version 8.0, we cannot request that the extended.enableMediaImageOperations attribute is returned for an HTTP GET request on the queue resource.
  • We must use one of these supported REST resources:

    • /queue
    • /subscription
    • /channel
    • /mqsc
    • /qmgr

      The /qmgr resource returns only a subset of the attributes when you query a remote queue manager: name, status.started, status.channelInitiatorState, status.ldapConnectionState, status.connectionCount, and status.publishSubscribeState.


About this task

To use the administrative REST API gateway to administer remote queue managers, we must prepare the queue managers for remote administration. That is, we must configure transmission queues, listeners, and sender and receiver channels between the gateway queue manager and the remote queue manager. We can then send a REST request to the remote queue manager by specifying the queue manager in the resource URL. The gateway queue manager is specified by either using the setmqweb command to set the mqRestGatewayQmgr attribute to the name of the gateway queue manager, or sending the name of the gateway queue manager in a header that is sent with the request. The request is sent through the gateway queue manager to the remote queue manager. The response is returned with a header that indicates the queue manager that was used as the gateway queue manager.


Procedure

  1. Configure communications between the gateway queue manager and the remote queue managers that we 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 Configure queue managers for remote administration.
  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. We 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 we 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


Results

An ibm-mq-rest-gateway-qmgr header is returned with the REST response. This header specifies which queue manager was used as the gateway queue manager.

If we have difficulty with using the administrative REST API to administer remote queue managers:

  • Check that the remote queue manager is running.
  • Check that the command server is running on the remote system.
  • Check that the channel disconnect interval has not expired. For example, if a channel started but then shut down after some time. This is especially important if you start the channels manually.


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:

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:
Figure 1. Diagram of example configuration for remote administration by using the REST API.
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"
    }]
}
Parent topic: Administration using the REST API