Create and using AMQP channels

When you install the IBM MQ support for MQ Light APIs into the IBM MQ installation, we can run IBM MQ MQSC commands (runmqsc) to define, alter, delete, start, and stop a channel. We can also view the status of a channel.

Before starting

This task assumes that we have installed the AMQP channel. You do this by selecting the AMQP Service component when installing IBM MQ. For more information, follow the link for the platform then find the table row for "AMQP Service":

• IBM MQ components for AIX systems
• IBM MQ rpm components for Linux systems
• IBM MQ Debian components for Linux Ubuntu systems
• IBM MQ features for Windows systems

To make a test connection to the queue manager, we must have an MQ Light client. MQ Light clients are available for Node.js, Ruby, Java, and Python. For more information on available clients, see the IBM MQ Light community website.

This task is based on the MQ Light Node.js client. However, the steps relating to the IBM MQ queue manager are the same for any client.

The following procedure assumes that we have an existing queue manager.

If you require a new queue manager, a sample script is included, which is located in the mqinstall/amqp/samples directory. The script creates a new queue manager, starts the AMQP service, creates a new channel called SAMPLE.AMQP.CHANNEL, and starts the channel. Note: AMQP channels do not support user defined AMQP services. AMQP channels only support the system default SYSTEM.AMQP.SERVICE service.

If you run the sample script, either SampleMQM.sh on Linux, or SampleMQM.bat on Windows, we can start the following procedure at 6.

We can use the default channel, SYSTEM.DEF.AMQP, to test MQ Light connections to the queue manager, or we can create a new channel.

The following procedure uses the default channel.

Procedure

1. Start runmqsc from the mqinstall/bin/ directory:

   runmqsc QMNAME

2. (Only necessary if your queue manager is IBM MQ Version 9.0.4 or earlier.) Check that the AMQP function is installed and working correctly. Use the START SERVICE command to start the IBM MQ service, which controls the JVM:

   START SERVICE(SYSTEM.AMQP.SERVICE)

   Note: From IBM MQ Version 9.1 the SYSTEM.AMQP.SERVICE has its CONTROL attribute set to QMGR. This causes the service to be started automatically when the queue manager is started. By setting the CONTROL attribute to MANUAL, we can prevent the service from being started when the queue manager is started.

   Upon the starting of the queue manager, the AMQP service and AMQP channel, if defined, are automatically started.

3. Set the MCAUSER user ID. When an AMQP client connects to a channel, the channel specifies an MCAUSER user ID, which is used on connections to the queue manager. The default value of MCAUSER is blank. Before any AMQP clients can connect to the queue manager we must specify an MCAUSER value, which must be a valid IBM MQ user who is authorized to publish and subscribe on IBM MQ topics.Note: On Windows, before IBM MQ Version 9.1.1, the MCAUSER user ID setting is only supported for user IDs up to 12 characters in length. From Version 9.1.1 Continuous Delivery, and from Version 9.2.0 Long Term Support, the 12 character limit is removed.
   1. Use the ALTER CHANNEL command to set the MCAUSER user ID:

      ALTER CHANNEL(SYSTEM.DEF.AMQP) CHLTYPE(AMQP) MCAUSER(User ID)

   2. Use the following two setmqaut commands to authorize your MCAUSER user ID to publish and subscribe to topics:

      setmqaut -m QMNAME -t topic -n SYSTEM.BASE.TOPIC -p MCAUSER
       -all +pub +sub

      and

      setmqaut -m QMNAME -t qmgr -p MCAUSER -all +connect

   If the channel is running while the MCAUSER user ID is added or altered, we must stop and restart the channel.Note: If the MCAUSER user ID is not set, or the MCAUSER user ID is not authorized to publish or subscribe to IBM MQ topics, we will receive an error message in the AMQP client.

4. Use the START CHANNEL command to start the default SYSTEM.DEF.AMQP channel:

   START CHANNEL(SYSTEM.DEF.AMQP)

5. Optional: To check the channel status, use the DISPLAY CHSTATUS command:

   DISPLAY CHSTATUS(SYSTEM.DEF.AMQP) CHLTYPE(AMQP)

   When the channel is running correctly, STATUS(RUNNING) is displayed in the command output.
6. Optional: Change the default port. The default port for AMQP 1.0 connections is 5672. If we are already using port 5672, which is possible if you previously installed MQ Light, you need to change the port that your AMQP channel uses. Use the ALTER CHANNEL command to change the port:

   ALTER CHANNEL(SYSTEM.DEF.AMQP) CHLTYPE(AMQP) PORT(NEW PORT NUMBER)

7. If we do not want to block or filter connections to the AMQP channel using channel authentication (CHLAUTH) rules, disable channel authentication on the queue manager as follows:

   alter qmgr chlauth(disabled) 
   

   You are not recommended to disable connection authentication on a production queue manager. We should only disable connection authentication in a development environment.

   Alternatively, configure the queue manager channel authentication rules to allow specific connections to the AMQP channel.

8. Optional: To enable SSL/TLS encryption on the channel, using the configured key repository for the queue manager, we must set the SSLCIPH attribute for the channel to an appropriate cipher specification. By default, the cipher specification is blank, meaning that SSL/TLS encryption is not used on the channel. Use the ALTER CHANNEL command to set a cipher specification. For example:

   ALTER CHANNEL(SYSTEM.DEF.AMQP) CHLTYPE(AMQP) SSLCIPH(CIPHER SPECIFICATION)
   

   Additionally, there are a number of other channel configuration options associated with SSL/TLS encryption that we can set as follows:
   • By default, the certificate in the queue manager key repository with label corresponding to the queue manager CERTLABL attribute is the name used by the SSL/TLS encryption for the channel. We can select a different certificate by setting CERTLABL. Use the ALTER CHANNEL command to specify the label for the required certificate:

     ALTER CHANNEL(SYSTEM.DEF.AMQP) CHLTYPE(AMQP) CERTLABL(CERTIFICATE LABEL)

   • We can set the channel to require a certificate from SSL/TLS client connections. We can select whether a certificate is required from a SSL/TLS client connection by setting the SSLCAUTH attribute. Use the ALTER CHANNEL command to set whether a certificate is required from a SSL/TLS client connection. For example:

     ALTER CHANNEL(SYSTEM.DEF.AMQP) CHLTYPE(AMQP) SSLCAUTH(REQUIRED or OPTIONAL)

   • If you set the SSLCAUTH attribute to REQUIRED, the Distinguished Name (DN) of the certificate from the client can be checked. To check the Distinguished Name of the certificate from the client, set the SSLPEER attribute. Use the ALTER CHANNEL command to check the Distinguished Name of the certificate from the client. For example:

     ALTER CHANNEL(SYSTEM.DEF.AMQP) CHLTYPE(AMQP) SSLPEER (DN SPECIFICATION)

     Alternatively, we can also use channel authentication records to allow or block connections because this method offers greater granularity compared to using the SSLPEER attribute. For more information on setting SSLPEER and using channel authentication records as an alternative, see SSL Peer.

9. Install the MQ Light Node.js client by running the following command:

   npm install mqlight

10. Navigate to the node_modules/mqlight/samples directory, and run the sample receiver application:
    • If we are using the default port number, we can run the sample receiver application:

      node recv.js

    • If you configured your AMQP channel to use a different port number, we can run the sample receiver application with a parameter to specify the new port number:

      node recv.js -s amqp://localhost:6789

    A successful connection to the default channel displays the following message:

    Connected to amqp://localhost:5672 using client-id recv_e79c55d
    Subscribed to pattern: public

    The application is now connected to the queue manager, and is waiting to receiving messages. It is subscribed to the topic public.Note: The client-id is automatically generated, unless you specify one using the -i parameter.
11. In a new command window, navigate to the node_modules/mqlight/samples directory, and run the sample sender application by running the following command:

    node send.js

    In the command window for the receiver application, the Hello World message is displayed.
12. Optional: Use the AMQSSUB IBM MQ sample to receive an MQ Light sample message. On Linux and Windows, the sample can be found in the following locations:
    • mqinstall/samp/bin directory on Linux.
    • mqinstall/Tools\c\Samples\Bin directory on Windows.
    1. Run the sample by running the following command:

       amqssub public QM-name.

    2. Send a message to the IBM MQ application by re-running the following command:

       node send.js

13. Optional: Use the DEFINE CHANNEL command to create more AMQP channels:

    DEFINE CHANNEL(MY.AMQP.CHANNEL) CHLTYPE(AMQP) PORT(2345)

    When you define a channel, it must be manually started, using the START CHANNEL command:

    START CHANNEL(MY.AMQP.CHANNEL)

    To check that the channel is running correctly we can run the sample receiver application, specifying the port of the new channel:

    node recv.js -s amqp://localhost:2345

What to do next

We can use the following commands to display the IBM MQ connections, stop the channel, and delete the channel:

DISPLAY CONN(*) TYPE(CONN) WHERE (CHANNEL EQ SYSTEM.DEF.AMQP)

Displays the IBM MQ connection that the AMQP channel made on the queue manager.

DISPLAY CHSTATUS(*) CHLTYPE(AMQP) CLIENTID(*) ALL

Displays a list of the AMQP clients connected to the specified channel.

STOP CHANNEL (MY.AMQP.CHANNEL)

Stops an AMQP channel, and closes the port that it is listening on.

DELETE CHANNEL (MY.AMQP.CHANNEL)

Deletes any channels that you created.Note: Do not delete the default channel SYSTEM.DEF.AMQP.

We can determine whether the AMQP capability is installed into the IBM MQ installation, and whether there is a queue manager associated with it, by using either runmqsc or PCF:

• Use runmqsc, display the attributes of the queue manager and check for AMQPCAP(YES).
• Use PCF, use the MQCMD_INQUIRE_Q_MGR command, and confirm the value of MQIA_AMQP_CAPABILITY.

• Removing the AMQP channel from queue managers
  We can remove the AMQP channel from queue managers by removing folders from the installation directory.
• AMQP channel log files
  The log files for AMQP channels are stored in the same IBM MQ data directory as IBM MQ log files.

Parent topic: Configure connections between the server and client

Related information

• strmqm
• Developing AMQP client applications
• Securing AMQP clients