Creating and using AMQP channels
When you install the IBM MQ support for MQ Light APIs into your 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 you begin
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 your platform then find the table row for "AMQP Service":- IBM MQ components for AIX systems
- IBM MQ components for HP-UX systems
- IBM MQ rpm components for Linux systems
- IBM MQ Debian components for Linux Ubuntu systems
- IBM MQ components for Solaris systems
- IBM MQ features for Windows systems
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 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
-
Start runmqsc from the
mqinstall/bin/ directory:
runmqsc QMNAME
-
(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.0.5 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.
-
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, the MCAUSER user ID setting is only
supported for user IDs up to 12 characters in length.
-
Use the ALTER CHANNEL command to set the MCAUSER user
ID:
ALTER CHANNEL(SYSTEM.DEF.AMQP) CHLTYPE(AMQP) MCAUSER(User ID)
-
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
andsetmqaut -m QMNAME -t qmgr -p MCAUSER -all +connect
-
Use the ALTER CHANNEL command to set the MCAUSER user
ID:
-
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 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. 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 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. 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)
- 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 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)
- 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.
- 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:
-
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, 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
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. - If you are using the default port number, we can run the sample receiver application:
-
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.
-
Run the sample by running the following command:
amqssub public QM-name.
-
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 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.