Basic configuration for the mqweb server

Before we can start to use the REST API or IBM MQ Console, we must install the correct components and configure the mqweb server that hosts the REST API or IBM MQ Console.

The procedure for this task focuses on a basic configuration for the mqweb server so that we can get started quickly with the REST API and IBM MQ Console. 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 mqweb server, see IBM MQ Console and REST API security.

Note: We must have access to the mqwebuser.xml file to complete this procedure:

  • On z/OS, we must be a user that has write access to the mqwebuser.xml file.
  • On all other operating systems, we must be a privileged user to access the mqwebuser.xml file.


Procedure

  1. Install the IBM MQ Console and REST API component:

  2. On z/OS, create the mqweb server that hosts the IBM MQ Console and REST API by running the crtmqweb script.

    This script creates the WebSphere Liberty user directory that contains the mqweb server configuration and log files. For more information about running the crtmqweb script, see Create the mqweb server.

  3. On z/OS, create a cataloged procedure to start the mqweb server.

  4. Replace the existing configuration file, mqwebuser.xml with the basic registry sample file. Copy basic_registry.xml from...

      MQ_INSTALLATION_PATH/web/mq/samp/configuration

    ...to the appropriate directory for the system, and rename the file to mqwebuser.xml:

    • On UNIX and Linux:

        var/mqm/web/installations/installationName/servers/mqweb

    • On Windows:

        MQ_DATA_PATH\web\installations\installationName\servers\mqweb

      By default, this path is C:\ProgramData\IBM\MQ.

    • On z/OS:

        WLP_user_directory/servers/mqweb

      Where WLP_user_directory is the directory specified when the crtmqweb script ran to create the mqweb server definition.

    The basic_registry.xml sample file configures four users:

      mqadmin
      An administrative user that is a member of the MQWebAdmin role.

      mqreader
      A read-only administrative user that is a member of the MQWebAdminRO role.

      mftadmin
      An administrative user that is a member of the MFTWebAdmin role.

      mftreader
      A read-only administrative user that is a member of the MFTWebAdminRO role.

    All users are also members of the MQWebUser role.

    For more information about the available roles, see Roles on the IBM MQ Console and REST API

  5. Optional: Edit mqwebuser.xml to add more users and groups. Assign those users and groups appropriate roles to be authorized to use the REST API or IBM MQ Console. We can also change the passwords for the users that are defined by default, and encode the new passwords. For more information, see Configure users and roles. Note:

    • On z/OS, if you add users to the MQWebUser role, we must also grant the mqweb started task user ID alternate user access to the user IDs with the MQWebUser role. For example:

        RDEFINE MQADMIN hlq.ALTERNATE.USER.userId UACC(NONE)
        PERMIT hlq.ALTERNATE.USER.userId CLASS(MQADMIN) ACCESS(UPDATE) ID(mqwebUserId)

    • To complete the steps for getting started with the messaging REST API, we must add a user to the mqwebuser.xml file. This user must have the same name as an existing IBM MQ user on the system. Following the same format as the other users in the xml file, add the user ID and a password after the following line in the xml file:

        <user name="mftreader" password="mftreader"/>

  6. On z/OS, set the WLP_USER_DIR environment variable so that the variable points to your mqweb server configuration, by entering 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. For example:

      export WLP_USER_DIR=/var/mqm/web/installation1

    For more information, see Create the mqweb server.

  7. By default, REST API and IBM MQ Console are available only from the same host as the mqweb server. Enable remote connections to the mqweb server by entering the following command:

      setmqweb properties -k httpHost -v hostname

    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, *, in double quotation marks, to specify all available network interfaces, as shown in the following example:

      setmqweb properties -k httpHost -v "*"

  8. Optional: By default, the administrative REST API for MFT is not enabled. To use this feature, we must enable it and configure a co-ordination queue manager:

    1. Enable the administrative REST API for MFT by entering the following command:

        setmqweb properties -k mqRestMftEnabled -v true

    2. Configure which queue manager is the co-ordination queue manager by entering the following command:

        setmqweb properties -k mqRestMftCoordinationQmgr -v qmgrName

      Where qmgrName is the name of the coordination queue manager.

    3. To enable POST calls, configure which queue manager is the command queue manager by entering the following command :

        setmqweb properties -k mqRestMftCommandQmgr -v qmgrName

      Where qmgrName is the name of the coordination queue manager.

  9. Start the mqweb server that supports the REST API and IBM MQ Console:

    We can stop the mqweb server at any time by stopping the mqweb server started task onz/OS, or by using the endmqweb command. However, if the mqweb server is not running, we cannot use the REST API or IBM MQ Console.


What to do next

  1. Configure mqweb server settings, including enabling HTTP connections, and changing the port number. For more information, see Configure the IBM MQ Console and REST API.

  2. Optional:, configure the REST API:

    1. Configure Cross Origin Resource Sharing for the REST API. By default, we 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. We can configure Cross Origin Resource Sharing (CORS) to allow cross-origin requests from specified URLs. For more information, see Configure CORS for the REST API.

    2. Configure the REST API for MFT. For more information, see Configure the REST API for MFT.

  3. Use the REST API or IBM MQ Console:

Parent topic: Configure the IBM MQ Console and REST API