Get an IBM MQ queue for development on Ubuntu

To see how IBM MQ works, you will be guided through creating and configuring a queue manager (server). Then, you will connect an application (client) to it.

After completing the tutorial, you will be able to send messages to and retrieve messages from a queue.

You can download, install, and run IBM MQ queue manager (server) in a variety of ways:

  • In a container.
  • In the IBM Cloud.
  • On various operating systems: Linux/Ubuntu (this tutorial) or Windows. For MacOS, use MQ on Containers.

Learning objectives

After completing this tutorial, you will understand these concepts:

  • IBM MQ queue managers
  • IBM MQ queues
  • Point-to-point messaging


The tutorial steps will have you download and install each of these prerequisites:

Estimated time

This tutorial should take about 30 minutes.


  1. Create a user and group for running MQ client applications
  2. Download IBM MQ
  3. Install IBM MQ
  4. Set up your MQ environment
  5. Create and configure a queue manager
  6. Put and get messages to and from a queue

Step 1. Create a user and group for running MQ client applications

Before we start the install, we need to create a group called “mqclient” and a user account called “app” in this group. These names allow us to configure the MQ objects we’ll work with, such as queues and channels.

We never need to actually log in as the user “app”. After it’s been created, please stay logged in to your own account.

Create the group mqclient from the terminal with the command:

sudo addgroup mqclient

You should see a confirmation that this was successful. Next, we create the user “app” and add this user to the group mqclient:

sudo adduser app

This prompts you to create a password for the account “app”, which you must do. You are then asked about other account details, which you can leave blank – just press ENTER until the account is created.

Now we need to add the user “app” to the “mqclient” group, and check this was successful.

sudo adduser app mqclient
groups app

We should get the following output:

Output from adding user and group

Now the account is set up correctly, we can move on to the actual install and configuration.

You now have 2 options for installing MQ on Ubuntu:

  • If you’d like to go through each step of the install and config, work through steps 2 through 5 of this tutorial and input the commands yourself. Then, continue with Step 6.

  • If you just want to get something working quickly, you can use this handy bash script that will install MQ and set up your development environment. If you use this script, make sure that you come back to this tutorial and continue with Step 6 to put and get your first message.

Made your choice? Definitely don’t want to use the bash script? Read on to install MQ and get your configuration set up.

Step 2. Download IBM MQ

We’re going to install MQ Advanced for Developers, then configure it so you can develop using MQ. Download the tar.gz file from here.

Step 3. Install IBM MQ

Unzip the folder you downloaded. The contents extract to a folder named “MQServer”. This contains many Debian packages that need to be installed. Note the location of this folder, e.g. /home/username/Downloads/MQServer. Open a terminal and type:

sudo ./ -text_only

This opens up the license in the terminal. Read the license and then press 1 to accept the terms. If you get an error and java isn’t in your path, do this:

sudo ./ -text_only -jre $(which java)

Next, we want to make sure that the apt installer can find package dependencies and install MQ properly. To do this, we need to add the folder to the apt cache.

  1. Navigate to the directory /etc/apt/sources.list.d
  2. Create a .list file with a name like ibmmq-install.list

Inside this file, put this line:

deb [trusted=yes] file:/home/username/Downloads/MQServer ./

then add the packages to the apt cache with:

sudo apt update

Now, we’re ready to install MQ. Install all the packages with the single command:

sudo apt install "ibmmq-*"

Now we’ve installed IBM MQ, let’s check that the installation was successful. Do this with the command /opt/mqm/bin/dspmqver. You should see output like this:

Output after installing IBM MQ


Step 4. Set up your MQ environment

Once the installation is complete, we need to add the user to the admin group “mqm” so you have MQ admin privileges such as the ability to create and start a queue manager. Important: This is not the user “app”, it’s your user account. You’re acting as the admin, and the user “app” is using the MQ setup that you have created. Add your user account with this command:

sudo adduser $(whoami) mqm

Now your user account (not the account called “app”) has been added to the group, we want to use these privileges to set up a queue manager. However, we need to make sure our mq environment is set up. Do this by entering:

cd /opt/mqm/bin
. setmqenv -s

This means you can now enter MQ commands to do a variety of tasks, e.g. create and start a queue manager. The environment is now set up, but only for the current shell. You will need to repeat this step if you use another shell or terminal.

Step 5. Create and configure a queue manager

Let’s create and start a queue manager. Use the command crtmqm to create a queue manager called QM1:

crtmqm QM1

Start our new queue manager with:

strmqm QM1

Now we’ve got a queue manager, it’s time to configure it and give it some MQ objects. We do this via a config script. Move to a folder you can download a file into and type:

wget mq-dev-config.mqsc

Once the script has downloaded, run it:

runmqsc QM1 < "./mq-dev-config.mqsc"

This command runs the queue manager QM1 with input commands from the .mqsc script. You should see output like this:

Output from running the queue manager

Finally, to finish the process off, you need to add the authority to the “mqclient” group so that its members (i.e. the user “app”) have the permission necessary to connect to a queue manager to put and get messages. Do this with the commands:

setmqaut -m QM1 -t qmgr -g mqclient +connect +inq
setmqaut -m QM1 -n DEV.** -t queue -g mqclient +put +get +browse +inq

Now, everything should be set up for you to use MQ! We’ll test this below by sending our first message.

Step 6. Put and get messages to and from a queue

So we’ve now got an installation of MQ that lets us connect to our preset queues and send messages.

If you’re joining us again after using the bash script, welcome back! If you used the bash script, you’ll need to do an extra step here, to allow your account to use the MQ commands. If you used the script, simply enter:

. /opt/mqm/bin/setmqenv -s

This will set your MQ environment for the current shell. This will need to be redone if you use a different shell or terminal. Done? Great, let’s get on with sending messages.

In order to use a sample message putting program, amqsputc, we need to export a couple of environment variables.

export MQSERVER='DEV.APP.SVRCONN/TCP/localhost(1414)'
export MQSAMP_USER_ID='app'

MQSERVER specifies the endpoint of the queue manager. MQSAMP_USER_ID specifies the account that has permission to run the sample programs included with the MQ installation.

Remember, there’s no need to log in as the user “app”. Just run this terminal command to execute the message putting script:

cd /opt/mqm/samp/bin
./amqsputc DEV.QUEUE.1 QM1

This should prompt you for the password for user account “app”. Enter this, then you will have the option to put one or more messages, separated by hitting ENTER, onto the queue DEV.QUEUE.1. When you’re done putting messages, hit ENTER twice to commit them to the queue.

Finally, we can get the messages from our queue. Run:

./amqsgetc DEV.QUEUE.1 QM1

Enter the password for the user “app” and your messages should be returned. The program waits for 15 seconds, in case new messages arrive, then exits. The returned message should look something like this:

Output showing returned message

To learn how to install, access, and put and get a message on the queue using the MQ Console, follow the steps in this tutorial.


In this tutorial, you configured the queue manager running on your Ubuntu machine for incoming client connections. The amqsputc application opened a queue and put messages to it. The amqsgetc application got messages from the same queue.

When you start developing your own client applications to connect to the queue manager, you’ll follow these steps:

  1. Configure the connection to the queue manager.
  2. Open a queue.
  3. Put a message on the queue.
  4. Get the message from the queue.
  5. Close the connection to the queue manager.

This process demonstrates the point-to-point style of messaging.

The amqsputc application acts as the producer point when it puts a message. The amqsgetc application acts as the consumer point when it gets the message from the queue.

In IBM MQ, the queue manager is effectively the server part of the system, and applications that connect to it are clients.

Usually it is the administrators that look after the MQ server where all the MQ objects are defined and the routing of messages happens. Client applications are created by developers and IBM MQ provides client libraries that developers must include in their applications. These libraries, also called MQ clients, address and use the MQ objects that admins have set up on the MQ server side. In more complex scenarios, the MQ libraries do most of the heavy messaging work for you, so you just have to learn how to use them.

Configuration is needed on both the server and the client sides for the messaging to work.

When you first start developing MQ client applications, it helps to have access to your own queue manager and a queue, for testing your client application against. Installing IBM MQ on your Ubuntu machine gives you access to a queue manager and many options for configuring MQ objects as you begin developing your own MQ applications.

Want to stop or remove your queue manager? Uninstall MQ?

If you intend to continue with the other tutorials in the MQ Essentials learning path, do not use these commands.

To stop your queue manager, issue this command: endmqm QM1

To remove your queue manager, issue this command: dltmqm QM1

To uninstall IBM MQ and remove the cached definition of the product, use this command: apt purge "ibmmq-*"

To keep the cached definition, use this command: apt remove "ibmmq-*"