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 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, you can start the following procedure at 6.
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.
The following procedure uses the default channel.
Procedure
-
Start runmqsc from the
mqinstall/bin/ directory:
-
(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.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, 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, 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
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 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,
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:
-
Navigate to the node_modules/mqlight/samples directory, and run the sample
receiver application:
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:
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:
-
Send a message to the IBM MQ application by
re-running the following command:
- 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
.