Before you can start the administrative REST API you must install the correct components,
enable the REST API, configure security, and start the mqweb
server.
Before you begin
On IBM® i, the commands should be running in
QSHELL.
About this task
The procedure for this task focuses on getting started quickly with the administrative REST API. The steps for configuring security outline how to set up a basic user registry, but other
options for configuring users and roles exist. For more information about configuring security for
the administrative REST API, see IBM
MQ Console and REST API security.
Procedure
-
Install the IBM MQ Console and REST API
component:
- On AIX®,install the mqm.web.rte fileset.
- On Linux®, install the
MQSeriesWeb component. For more information about installing components and
features on Linux, see Linux installation tasks.
- On Windows, install the
Web Administration feature. For more information about installing components
and features on Windows, see Windows installation tasks.
- On z/OS®, install the
IBM MQ for z/OS Unix System Services Web Components feature. For more
information about installing components and features on z/OS, see z/OS installation tasks.
- Optional:
From IBM MQ 9.0.2, the administrative REST API is
enabled by default. However, in IBM MQ 9.0.1, the
administrative REST API is disabled by default. If you are using IBM MQ 9.0.1, enable the REST API by adding the following XML to the
mqwebuser.xml file, within the
<server>
tags:
<variable name="mqRestAutostart" value="true"/>
The
mqwebuser.xml can be found in one of the following directories:
-
From IBM MQ 9.0.2, security is enabled for the
administrative REST API. You must configure users and roles before you can use the administrative REST API:
-
Copy the basic_registry.xml file from the
MQ_INSTALLATION_PATH
/web/mq/samp/configuration directory.
-
Place the sample XML file in the appropriate directory:
-
Rename the sample XML file to
mqwebuser.xml
.
Note: This renamed file replaces an existing file that is also used for the IBM MQ Console. Therefore, if you changed the
mqwebuser.xml
file for the IBM MQ Console, copy your changes to the new XML file before you rename it.
- Optional:
Edit the
mqwebuser.xml
file to add users and groups. Assign those users and
groups appropriate roles to be authorized to use the administrative REST API. You can also change
the passwords for the users that are defined by default, and encode the new passwords. For more
information, see Configuring users and
roles.
-
Enable remote connections to the mqweb server:
where
hostname specifies the IP address, domain name server (DNS) host name
with domain name suffix, or the DNS host name of the server where
IBM MQ is installed. Use an asterisk, *, to specify all available
network interfaces.
Attention:
Before issuing either the setmqweb or dspmqweb commands on
z/OS, you must set the WLP_USER_DIR environment
variable, so that the variable points to your mqweb server configuration.
To do this, issue the following
command:
export WLP_USER_DIR=WLP_user_directory
where
WLP_user_directory
is the name of the directory that is passed
to
crtmqweb.sh
. For
example:
export WLP_USER_DIR=/var/mqm/web/installation1
For more information, see Create
the Liberty server definition.
-
Start the mqweb server that supports the REST API:
What to do next
- Choose how users of the administrative REST API authenticate with the mqweb
server. You do not have to use the same method for all users. The following options are available:
- Let users authenticate by using HTTP basic authentication. In this case, a user name and
password are encoded, but not encrypted, and sent with each REST API request to authenticate and
authorize the user for that request. In order for this authentication to be secure, you must use a
secure connection. That is, you must use HTTPS. For more information, see Using HTTP basic authentication with the
REST API.
- Let users authenticate by using token authentication. In this case, a user provides a user ID
and password to the REST API
login
resource with the HTTP POST method. An LTPA token
is generated that enables the user to remain logged in and authorized for a set amount of time. In
order for this authentication to be secure, you must use a secure connection. That is, you must use
HTTPS. For more information, see Using token based authentication with the REST API.
- Let users authenticate by using client certificates. In this case, the user does not use a user
ID or password to log in to the administrative REST API, but uses the client certificate instead.
For more information, see Using client
certificate authentication with the REST API.
- Configure REST API settings, including enabling HTTP connections, and changing
the port number. For more information, see Configuring the IBM MQ Console and REST API.
- Optionally, configure the REST API for MFT. For more information, see Required configuration for the MFT REST API.
- Optionally, configure Cross Origin Resource Sharing for the REST API. By default,
you cannot access the REST API from web resources that are not hosted on the same domain as the REST API. That is, cross-origin requests are not enabled. You can configure Cross Origin Resource Sharing
(CORS) to allow cross-origin requests from specified URLs. For more information, see
Configuring CORS for the REST API.
- Use the REST API. For more information, see Using the administrative REST API, Remote administration using the REST API, and the Administrative REST API
reference.
Note: You can stop the mqweb server at any time by using the endmqweb command.
However, if the mqweb server is not running, you cannot use the REST API or IBM MQ Console.