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.
Before you begin
You can prevent remote administration by disabling the administrative REST API gateway. For more information, see Configuring the administrative REST API gateway.
- 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 you want to configure as the gateway queue manager must be in the same installation as the mqweb server.
- The remote queue manager that you want to administer must be at IBM MQ 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®, you cannot request that the
dataCollection.statistics
attribute is returned for an HTTP GET request on thequeue
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 8.0, you cannot request that the
extended.enableMediaImageOperations
attribute is returned for an HTTP GET request on thequeue
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
, andstatus.publishSubscribeState
.
About this task
mqRestGatewayQmgr
attribute by using the setmqweb command 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
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
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
, onMachine 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
, onMachine 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
, onMachine 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"
}]
}