[Windows][UNIX][Linux]

Creating and using AMQP channels

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

Before you begin

This task assumes that you 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 your platform then find the table row for "AMQP Service":

To make a test connection to the queue manager, you 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.

About this task

The following procedure assumes that you have an existing non-production queue manager, upgraded to command level 801. To enable the 801 command level for your queue manager, you can run the following command:

strmqm -e CMDLEVEL=801 <QMNAME>
You must restart the queue manager after running this command. 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 at command level 801, starts the AMQP service, creates a new channel called SAMPLE.AMQP.CHANNEL, and starts the channel. If you run the sample script, either SampleMQM.sh on Linux, or SampleMQM.bat on Windows, you can start the following procedure at Step 6.
Note: AMQP channels do not support user defined AMQP services. AMQP channels only support the system default SYSTEM.AMQP.SERVICE service.

If you upgrade an existing queue manager to command level 801, a new default channel object is created. The default channel is called SYSTEM.DEF.AMQP. You can use the default channel to test MQ Light connections to the queue manager or you can create a new channel.

The following procedure uses the default channel.

Procedure

  1. Start runmqsc from the <mqinstall>/bin/ directory:
    
    runmqsc <QMNAME>
    
  2. 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)
    
  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 you must specify an MCAUSER value, which must be a valid IBM MQ user who is authorized to publish and subscribe on IBM MQ topics.
    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, you 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, you 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: If you want 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 you 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 you 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. You 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: If you want to enable SSL/TLS encryption on the channel, using the configured key repository for the queue manager, you 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 you 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. You 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)
    • You can set the channel to require a certificate from SSL/TLS client connections. You can select whether a certificate is required from a SSL/TLS client connection by setting SSLCAUTH. 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)
    • [V8.0.0.15 Jun 2020]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, you 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 you are using the default port number, you can run the sample receiver application:
      
      node recv.js
      
    • If you configured your AMQP channel to use a different port number, you 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:
    • [Linux]mqinstall/samp/bin directory on Linux.
    • [Windows]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 you can run the sample receiver application, specifying the port of the new channel:
    
    node recv.js -s amqp://localhost:2345
    

What to do next

You 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.
You 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:
  • Using runmqsc, display the attributes of the queue manager and check for AMQPCAP(YES).
  • Using PCF, use the MQCMD_INQUIRE_Q_MGR command, and confirm the value of MQIA_AMQP_CAPABILITY.