Planning to use the IBM MQ Console and REST API on z/OS

The IBM® MQ Console and REST API are applications that run in a WebSphere® Application Server Liberty (Liberty) server known as mqweb. The mqweb server runs as a started task. The MQ Console allows a web browser to be used to administer queue managers. The REST API provides a simple programmatic interface for applications to do queue manager administration, and to perform messaging.

Installation and configuration files

You need to install the IBM MQ for z/OS® UNIX System Services Web Components feature, which will install the files needed to run the mqweb server in z/OS UNIX System Services (USS). You need to be familiar with USS to be able to configure and manage the mqweb server.

If you have installed IBM MQ on one system, and run IBM MQ on a different system, you should copy the IBM MQ ZFS created during the installation to the processing system, and mount it read only.

You need to create, and decide upon the location for, a Liberty user directory when you create the mqweb server. This directory contains configuration and log files, and the location can be something similar to /var/mqm/mqweb.

Using the MQ Console and REST API with queue managers at different levels

The MQ Console and REST API can directly interact only with queue managers that run at the same Version, Release, and Modification (VRM) . For example, the MQ Console and REST API shipped with IBM MQ 9.0.5 can interact only with local queue managers at IBM MQ 9.0.5, and the MQ Console and REST API shipped with IBM MQ 9.0.5 can interact only with local queue managers at IBM MQ 9.0.5.

For the REST API, you can administer queue managers at a different version from the mqweb server by configuring a gateway queue manager. However, you need at least one queue manager at the same version as the mqweb server to act as the gateway queue manager. For more information, see Remote administration using the REST API.

Migration

If you have only one queue manager, you can run the mqweb server as a single started task, and change the libraries it uses when you migrate your queue manager.

If you have more than one queue manager, during migration you can start mqweb servers at different versions by using started tasks with different names. These names can be any name you want. For example, you can start an IBM MQ 9.0.5 mqweb server using a started task named MQWB0905, and an IBM MQ 9.0.4 mqweb server using a started task named MQWB0904.

Then, when you migrate the queue managers from one version to a later version, the queue managers become available in the mqweb server for the later version, and are no longer available in the mqweb server for the earlier version.

Once you have migrated all the queue managers to the later version, you can delete the mqweb server for the earlier version.

HTTP ports

The mqweb server uses up to two ports for HTTP:

One for HTTPS, with a default value of 9443.
One for HTTP. HTTP is not enabled by default, but if enabled, has a default value of 9080.

If the default port values are in use, you must allocate other ports. If you have more than one mqweb server running simultaneously for more than one version of IBM MQ, you must allocate separate ports for each version. For more information on setting the ports that the mqweb server uses, see Configuring the HTTP and HTTPS ports.

You can use the following TSO command to display information about a port:

NETSTAT TCP tcpip (PORT portNumber)

where tcpip is the name of the TCP/IP address space, and portNumber specifies the number of the port to display information about.

Security - starting the mqweb server

The mqweb server user ID needs certain authorities. For more information, see Authority required by the mqweb server started task user ID.

Security - using the MQ Console and REST API

When you use the MQ Console and REST API, you must authenticate as a user that is included in a configured registry. These users are assigned specific roles that determine the actions the users can perform. For example, to use the messaging REST API, a user must be assigned the MQWebUser role. For more information about the available roles for the MQ Console and REST API, and the access that these roles grant, see Roles on the MQ Console and REST API.

For more information about configuring security for the MQ Console and REST API, see MQ Console and REST API security.