Configure a queue manager to accept client connections on z/OS

Before we can run the sample applications, we must first create a queue manager. You can then configure the queue manager to securely accept incoming connection requests from applications that are running in client mode.


Before starting

Ensure the queue manager already exists and has been started. Determine whether channel authentication records are already enabled by issuing the MQSC command: 
DISPLAY QMGR CHLAUTH
Important: This task expects that channel authentication records are enabled. If this is a queue manager used by other users and applications, changing this setting will affect all other users and applications. If your queue manager does not make use of channel authentication records then step 4 can be replaced with an alternate authentication method (for example a security exit) which sets the MCAUSER to the non-privileged-user-id we will obtain in step 1.

We must know which channel name your application expects to use so that the application can be permitted to use the channel. We must also know which objects, for example queues or topics, the application expects to use so that your application can be permitted to use them.


This task creates a non-privileged user ID to be used for a client application which connects to the queue manager. Access is granted for the client application only to be able to use the channel it needs and the queue it needs by use of this user ID.


Procedure

  1. Obtain a user ID on the system your queue manager is running on.

    For this task this user ID must not be a privileged administrative user. This user ID is the authority under which the client connection will run on the queue manager.

  2. Start a listener program.
    1. Ensure that your channel initiator is started. If not, start it by issuing the START CHINIT command.
    2. Start the listener program by issuing the following command: 
      START LISTENER TRPTYPE(TCP) PORT(nnnn)
      where nnnn is your chosen port number.

  3. If the application uses the SYSTEM.DEF.SVRCONN then this channel is already defined. If your application uses another channel, create it by issuing the MQSC command: 
    DEFINE CHANNEL(' channel-name ') CHLTYPE(SVRCONN) TRPTYPE(TCP) +
DESCR('Channel for use by sample programs')

    • channel-name is the name of our channel.

  4. Create a channel authentication rule allowing only the IP address of our client system to use the channel by issuing the MQSC command: 
    SET CHLAUTH(' channel-name ') TYPE(ADDRESSMAP) ADDRESS(' client-machine-IP-address ') +
MCAUSER(' non-privileged-user-id ')
    where

    • channel-name is the name of our channel.
    • client-machine-IP-address is the IP address of our client system. If your sample client application is running on the same machine as the queue manager then use an IP address of '127.0.0.1' if the application is going to connect using 'localhost'. If several different client machines are going to connect in, we can use a pattern or a range instead of a single IP address. See Generic IP addresses for details.
    • non-privileged-user-id is the user ID you obtained in step 1

  5. If the application uses the SYSTEM.DEFAULT.LOCAL.QUEUE, then this queue is already defined. If the application uses another queue, create it by issuing the MQSC command: 
    DEFINE QLOCAL(' queue-name ') DESCR('Queue for use by sample programs')
    where queue-name is the name of our queue.
  6. Grant access to connect to and inquire the queue manager:
    1. Ensure that your channel initiator is started. If not, start the channel initiator by issuing the START CHINIT command.
    2. Start a TCP listener, for example issue the following command: 
      START LISTENER TRPTYPE(TCP) PORT(nnnn)
      where nnnn is your chosen port number.

  7. If the application is a point-to-point application, that is it makes use of queues, grant access to allow inquiring and the putting and getting messages using your queue by the user ID to be used, by issuing the MQSC commands: Issue the RACF commands:
    RDEFINE MQQUEUE qmgr-name.QUEUE. queue-name UACC(NONE)

PERMIT qmgr-name.QUEUE. queue-name CLASS(MQQUEUE) ID(non-privileged-user-id) ACCESS(UPDATE)
    where

    • qmgr-name is the name of our queue manager
    • queue-name is the name of our queue.
    • non-privileged-user-id is the user ID you obtained in step 1

  8. If the application is a publish/subscribe application, that is it makes use of topics, grant access to allow publishing and subscribing using your topic by the user ID to be used, by issuing the following RACF commands: 
    RDEFINE MQTOPIC qmgr-name.PUBLISH.SYSTEM.BASE.TOPIC UACC(NONE)

PERMIT qmgr-name.PUBLISH.SYSTEM.BASE.TOPIC CLASS(MQTOPIC) ID(non-privileged-user-id) ACCESS(UPDATE)

RDEFINE MQTOPIC qmgr-name.SUBSCRIBE.SYSTEM.BASE.TOPIC UACC(NONE)

PERMIT qmgr-name.SUBSCRIBE.SYSTEM.BASE.TOPIC CLASS(MQTOPIC) ID(non-privileged-user-id) ACCESS(UPDATE)
    where

    • qmgr-name is the name of our queue manager
    • non-privileged-user-id is the user ID you obtained in step 1
    • This will give non-privileged-user-id access to any topic in the topic tree, alternatively, we can define a topic object using DEFINE TOPIC and grant accesses only to the part of the topic tree referenced by that topic object. For more information, see Control user access to topics.


What to do next

Your client application can now connect to the queue manager and put or get messages using the queue. Parent topic: Use the sample programs for z/OS


Related information