Creating and using AMQP channels

When you install the IBM® MQ support for the AMQP Service Component 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 can use any AMQP clients that implement the OASIS AMQP 1.0 protocol, such as MQ Light and Apache Qpid clients like Apache Qpid Proton and Apache Qpid JMS.

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 queue manager.

[Long Term Support] 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. You can only define one instance of this service for each queue manager.

[Long Term Support] [Windows] [Linux] If you run the sample script, either SampleMQM.sh on Linux, or SampleMQM.bat on Windows, you can start the following procedure at 6.

[Long Term Support] You can use the default channel, SYSTEM.DEF.AMQP, to test MQ Light connections to the queue manager, or you can create a new channel.

[MQ 9.2.2 Mar 2021] From IBM MQ 9.2.2, you can use only the default channel, SYSTEM.DEF.AMQP, to test MQ Light connections to the queue manager.

The following procedure uses the default channel.

Procedure

Start runmqsc from the mqinstall/bin/ directory:
```
runmqsc QMNAME
```
(Only necessary if your queue manager is IBM MQ 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 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, you 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.
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.
Note: On Windows, before IBM MQ 9.1.1, the MCAUSER user ID setting is only supported for user IDs up to 12 characters in length. From IBM MQ 9.1.1 Continuous Delivery, and from IBM MQ 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, 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.
Use the START CHANNEL command to start the default SYSTEM.DEF.AMQP channel:
```
START CHANNEL(SYSTEM.DEF.AMQP)
```
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.
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)
```
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.
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 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, 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.
Install the MQ Light Node.js client by running the following command:
```
npm install mqlight
```
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.
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.
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
```
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.