IBM MQ AMQP messaging is built into IBM MQ 10 by default. Pull the MQ 10 container image, run it, and connect apps on port 5672 without creating a custom build. This tutorial shows you how to enable IBM MQ AMQP messaging in a container and optionally add TLS for secure client connections.

Advanced Message Queuing Protocol (AMQP) is a non-proprietary messaging protocol with an open standard wire format. Apache Qpid is an open-source project that provides messaging tools and client libraries for AMQP-based applications.

IBM MQ supports AMQP APIs through an AMQP channel that accepts connections from AMQP client applications. With IBM MQ, Apache Qpid applications can perform publish/subscribe and point-to-point messaging. Those AMQP applications can also exchange messages with applications that use other IBM MQ API stacks.

Prerequisites

To complete this tutorial, you need to install:

Git command line
Docker or Podman. Podman commands shown in these tutorial steps can be replaced with Docker commands.
Optionally for TLS: keytool, which is included in Java JDKs. You can use SDKMAN to install and manage versions of Java and Maven.
Optionally for TLS: openssl. In most cases, you already have it.

Steps

First, enable and run the IBM MQ AMQP service, and then, if desired, enable TLS over AMQP.

Enable and run the IBM MQ AMQP service

For AMQP client applications to communicate with IBM MQ, the IBM MQ AMQP service must be running. To enable the AMQP service, clone and customize the IBM MQ Container repository.

Clone the MQ Container repository by running this command:
```
 git clone -b 10.0.0 https://github.com/ibm-messaging/mq-container.git
```
CD to the cloned repository, mq-container.
Enable AMQP in the MQ container by editing the Dockerfile-server file, scrolling down to the "Build stage to reduce MQ packages using genmqpkg" section, navigating to the line that starts with "ENV" and changing the third line from genmqpkg_incamqp=0 to genmqpkg_incamqp=1.
Set up AMQP authority, channel, and service properties by adding the contents of the add-dev.mqsc.tpl file to the bottom of the /incubating/mqadvanced-server-dev/10-dev.mqsc.tpl file in your cloned repository.
Build a developer Docker image.

Make sure you are in the mq-container directory. Then, build a development server image.
```
 make build-devserver
```
If you are building your container on Windows, first set up WSL 2 by following the blog Building a customized IBM MQ Container on WSL 2.

If you are using an Apple Silicon ARM-based macOS machine, you can run the AMD64 image in emulation mode. You need at least macOS Sequoia 15. On macOS, build the image with this command:
```
 ARCH=amd64 make build-devserver
```
If you see this error Error response from daemon: network mode "build" not supported by buildkit, then run this command:
```
 DOCKER_BUILDKIT=0 make build-devserver
```
Then, check the image ID:
```
 podman image ls
```
You should see output similar to this output:

Start the customized MQ container.

 podman run --env LANG=C --env LICENSE=accept --env MQ_QMGR_NAME=QM1 --env MQ_APP_PASSWORD=passw0rd --env MQ_ADMIN_PASSWORD=passw0rd --publish 1414:1414 --publish 9443:9443 --publish 5672:5672 --detach ibm-mqadvanced-server-dev:10.0.0.0-amd64

Verify that the AMQP port is enabled on port 5672 in your MQ queue manager by running:
```
 podman ps
```
You should see output similar to this output:

Enable TLS over AMQP

Create a server keystore

If you want to enable TLS, you need a .p12 keystore for the server and a truststore for the client. The container includes a test script that generates both files.

Go to the directory mq-container/test/tls. You can use the keystore in this directory with the default password or generate your own using the generate-test-cert.sh script.

If you choose to generate your own, create a working directory, for example, mq-container/keys, and copy generate-test-cert.sh to that directory.
```
 mkdir <path to mq-container directory>/keys
 cd <path to mq-container directory>/keys
 cp ../test/tls/*.sh .
```
Edit the generate-test-cert.sh file and change the password that will be used for the keystore. For example:
```
 PASSWORD=<Any secure password you want>
```
In this tutorial, the example password is PASSWORD=SecureKeySt0re.

Save the file, and run the script.
```
 ./generate-test-cert.sh
```
A directory listing should show the new keystore and client trust store. You will use the server.p12 keystore in the next step.

You can use the client-trust.jks client trust store for any Java clients that want to connect to your AMQP queue manager server over TLS.
Create MQSC instructions to configure AMQP over TLS.

Create a new file tls-amqp.mqsc and add the contents of add-tls-amqp.mqsc to it.

Modify the keystore password to the password you used to create the keystore in step 1.
```
 ALTER QMGR KEYRPWD('SecureKeySt0re')
```
Leave the location of the server.p12 as is. You map the location of the server.p12 to this value when you start the queue manager.
```
 ALTER QMGR SSLKEYR('/amqp-tls/server.p12')
```
Start the customized MQ container.
```
 podman run --env LICENSE=accept --env MQ_QMGR_NAME=QM1 --env MQ_APP_PASSWORD=passw0rd --env MQ_ADMIN_PASSWORD=passw0rd --volume <path_to_tls_folder>:/amqp-tls --volume <path_to_tls-amqp.mqsc>:/etc/mqm/tls-amqp.mqsc --publish 1414:1414 --publish 9443:9443 --publish 5672:5672 --detach ibm-mqadvanced-server-dev:10.0.0.0-amd64
```
Note: There is no TLS build; you are using the same build from the previous step. In this run, you have added two extra volumes to enable TLS.
```
 --volume <path_to_tls_folder>:/amqp-tls
```
This maps the location of the keystore as the volume /amqp-tls. In our case this was set to:
```
 --volume ./keys:/amqp-tls
```
Recall that amqp-tls/server.p12 is the path you added to the MQSC, which corresponds to the second additional volume.
```
 path_to_tls-amqp.mqsc
```
In our case, this was set to:
```
 --volume ./tls-amqp.mqsc:/etc/mqm/tls-amqp.mqsc
```
This maps to the AMQP TLS MQSC file you created in step 2. The MQSC with the associated keystore are provided together on the podman run command that starts the container. This allows the container to successfully configure TLS for the AMQP channel.

On MacOS the container will start although you will see the following warning:
```
 WARNING: image platform (linux/amd64) does not match the expected platform (linux/arm64)
```
Verify that the AMQP port is enabled on port 5672 in your MQ queue manager by running:
```
 podman ps
```
You should see output similar to this output:
Verify that TLS is configured.

Open a terminal on your container by running the following command:
```
 podman exec -ti <container_id> /bin/bash
```
Start the MQSC command line:
```
 runmqsc
```
Run the MQSC command.
```
 DISPLAY QMGR SSLKEYR
```
A response showing SSLKEYR(/amqp-tls/server.p12) as below confirms that the key store registry has been successfully configured.

Exit runmqsc.
```
 quit
```
Exit out of the container.
```
 exit
```

Summary and next steps

With this tutorial, you enabled IBM MQ AMQP messaging in a customized container and verified that the AMQP channel is available on port 5672. If needed, you also configured TLS so AMQP clients can connect securely.

With IBM MQ AMQP messaging enabled, you can use AMQP-based toolkits and frameworks in your MQ applications. For example, you can build a simple Vert.x reactive application or develop JMS applications with Quarkus and GraalVM.

Products

Languages

Technologies

Events

External Resources

Champions

Set up IBM MQ AMQP messaging

Prerequisites

Steps

Enable and run the IBM MQ AMQP service

Enable TLS over AMQP

Summary and next steps