View Only

A quick guide to installing IBM MQ using Ubuntu Linux and Ansible Galaxy

By Martin Evans posted Wed December 13, 2023 07:08 AM


In this article I will provide you with step-by-step instructions on how to install IBM MQ for developers on an Ubuntu Linux server using the IBM MQ Ansible Galaxy collection of playbooks and modules. I will assume you don’t have Ansible installed so if you have it already skip the 'apt' install commands. Following these instructions will install IBM MQ for developers, setup users, create a test queue manager called QM1, start the web console and create some sample MQ objects. As this is just a test server/sandbox environment - for simplicity I will use the 'root' user.

The IBM MQ Ansible Galaxy collection supports other operating systems too, for more details see, IBM MQ Ansible Galaxy Collection

Want to get involved? Head over to the open-source IBM mq-ansible project on GitHub

Install Ansible and the IBM MQ Ansible Galaxy Collection

Full details for an Ansible installation can be found here, installing-ansible-on-ubuntu

STEP Type the following to install Ansible using APT,

$ apt update

$ apt install software-properties-common

$ add-apt-repository --yes --update ppa:ansible/ansible

$ apt install --yes ansible

STEP Type the following to install the IBM MQ collection,

$ ansible-galaxy collection install ibm_messaging.ibmmq

IBM MQ Ansible Setup

STEP Create a file called setup-playbook.yml with the following contents:


  - name: prepares MQ server

    hosts: localhost

    connection: local

    become: true


      PATH: /opt/mqm/bin:{{ ansible_env.PATH }}


      - ibm_messaging.ibmmq


      - name: Import downloadmq role


          name: ibm_messaging.ibmmq.downloadmq

      - name: Import setupusers role


          name: ibm_messaging.ibmmq.setupusers

      - name: Import installmq role


          name: ibm_messaging.ibmmq.installmq

      - name: Import setupenvironment role


          name: ibm_messaging.ibmmq.setupenvironment

      - name: Get MQSC file

        become: true

        become_user: mqm


          name: ibm_messaging.ibmmq.getconfig


          mqsc_local: dev-config.mqsc

      - name: Set up web console

        become: true

        become_user: mqm


          name: ibm_messaging.ibmmq.setupconsole

      - name: Start web console

        become: true

        become_user: mqm


          name: ibm_messaging.ibmmq.startconsole

      - name: Create a queue manager

        become_user: mqm

        tags: ["queue"]


          qmname: QM1

          state: present

      - name: Use our MQSC File

        become: true

        become_user: mqm


          qmname: QM1

          state: running

          mqsc_file: /var/mqm/dev-config.mqsc

STEP Copy the example MQSC file to the same folder as the playbook, the example comes with the Galaxy collection so yours might be in a different folder if you already had Ansible installed, this article just uses the default which puts them in your home folder. 


$ cp .ansible/collections/ansible_collections/ibm_messaging/ibmmq/playbooks/files/dev-config.mqsc ./

Optionally, if you don’t have the supplied example MQSC file or you want to use your own file just do something like,

$ echo "define ql(test)" > dev-config.mqsc

Install IBM MQ and create a Queue Manager

STEP Now you can install IBM MQ on this server/localhost using this command,

$ ansible-playbook setup-playbook.yml -e 'ibmMqLicence=accept'

When the installation has finished you can su to the 'mqm' user and observe your running queue manager e.g.,

$ su - mqm

$ dspmq

That's pretty much it, if you want to install on a remote host, make sure you have SSH access, change these lines in setup-playbook.yml

hosts: localhost

    connection: local


hosts: mqservers

Create an ini file with the target server details, e.g.,


mq-server1 ansible_ssh_user=root

Run the playbook with the -i option,

$ ansible-playbook setup-playbook.yml -i ./inventory.ini -e 'ibmMqLicence=accept'

Accessing the IBM MQ Web Console

Firstly I recommend you change the default passwords, edit the mqwebuser.xml file,

$ vi /var/mqm/web/installations/Installation1/servers/mqweb/mqwebuser.xml

Search for 'password' and you'll see the usernames and their password, e.g. 'mqadmin' replace the passwords with your own choice of password.

Now find the URL for the console,

$ dspmqweb

This will give you the URL for the console e.g.,


Use the username/password combination from mqwebuser.xml

IBM Legal Disclaimer

This content was provided for informational purposes only. The opinions and insights discussed are those of the presenter and guests and do not necessarily represent those of the IBM Corporation.

Nothing contained in these materials or the products discussed is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers, or altering the terms and conditions of any agreement you have with IBM.

The information presented is not intended to imply that any actions taken by you will result in any specific result or benefit and should not be relied on in making a purchasing decision. IBM does not warrant that any systems, products or services are immune from, or will make your enterprise immune from, the malicious or illegal contact of any party.

All product plans, directions and intent are subject to change or withdrawal without notice. References to IBM products, programs or services do not imply that they will be available in all countries in which IBM operates. IBM, the IBM logo, and other IBM products and services are trademarks of the International Business Machines Corporation, in the United States, other countries or both. Other company, product, or services names may be trademarks or services marks of others.

For copyright and trademark information go to:





Tue March 05, 2024 08:59 AM

The Ansible playbook has been updated to allow installation of MQ from a local file ( rather than pulling the installation image from the site containing versions of  MQ Advanced for Developers ).

You need to add two variables in the downloadmq role section ...  local_source and mq_local_path . 

In my case I used this to install some early(beta) code at  version  MQ 9.3.5 

[Additions  to the downloadmq role section in  bold text below ] 

      - name: Import downloadmq role


          name: ibm_messaging.ibmmq.downloadmq


          local_source: true

          mq_local_path: /tmp/MQAdv935Beta_LinuxX64.tar.gz


Mon January 15, 2024 02:39 PM

For AIX, it's trivial to install ansible provided you've already got the dnf command setup. There's lots of easily-findable instructions on how to do that, and it gives AIX easy access to a bunch of pre-built open source projects. Basically, dnf comes as a standard AIX installable (installp) package, and from there it's much like any rpm-based Linux.

Just make sure you've got /opt/freeware/bin in your PATH as that is where these AIX packages get installed.

So first it was simply a  matter of sudo dnf install ansible. And from there, things like the ansible-galaxy command just work.

Fri December 15, 2023 03:58 AM

Hi Morag,

That's a great question, and perhaps I should have titled the blog more generically "Installing IBM MQ Using Ubuntu" because I think all you would need to do is follow the instructions but do a remote install, using the inventory file approach, to an AIX host instead of an Ubuntu host. The Ansible playbooks/modules check the target for its platform type. If you want to use AIX to drive the playbook then you'll need to install Ansible on AIX – that’s not something I’ve done before. I chose Ubuntu as an example because it’s freely available, the GitHub repository has some notes on AIX and Windows.


Fri December 15, 2023 03:30 AM

I see that the IBM MQ Ansible collection is available on AIX too. Do you have any instructions on how to do this on AIX? There don't seem to be install instructions for Ansible on AIX.