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

Before you begin

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

• The mqweb server must be configured and started. For more information about configuring and starting the mqweb server, see Get started with the administrative REST API.
• The queue manager to configure as the gateway queue manager must be in the same installation as the mqweb server.
• The remote queue manager to administer must be at Version 8.0 or later.
• You must ensure that any attributes that are specified in your request are valid for the system that you 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.
• You must ensure that any attributes that are specified in your request are valid for the level of IBM MQ that you 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.
• You 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

Procedure

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

Example

• 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.

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

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

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

{
   "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"
    }]
}