Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


📝 Interested in contributing to this project? Please read our IBM Contributor License Agreement and our Contributing Guide.

A collection for automating the installation and configuration of IBM MQ using Ansible on Ubuntu machines. Our aim is to make MQ-Ansible extensible for further and more detailed IBM MQ configuration.

This directory contains:

  • ansible roles for the installation and configuration of IBM MQ.
  • module to create and configure a queue manager.
  • playbook ibmmq.yml which implements the roles and module.

For a detailed explanation and documentation on how MQ-Ansible works, click here.


  • ansible and ansible-lint are required on your local machine to run playbooks implementing this collection.
  • An Ubuntu target machine is required to run MQ.

Roles for IBM MQ installation

The roles in this collection carry out an installation of IBM MQ Advanced on an Ubuntu target machine with ansible roles as yaml files. The roles have been implemented to set up the required users on the machine, download the software, install and configure IBM MQ, copy over a configurable dev-config.mqsc file ready to be run on the target machine, and set and start the web console. Developers can change this file to allow better configuration of their queue managers.


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

    - role: setupusers
        gid: 989
    - downloadmq
    - installmq
    - getconfig
    - setupconsole
    - startconsole

Modules for IBM MQ resources' configuration

  • Creates, starts, deletes an IBM MQ queue manager and runs an MQSC file. See the documentation here.

Run our sample playbook

Setup (inventory.ini)

Note: Ansible must be installed on the local machine. (Installation guide)

Before running the playbook implementing our modules and roles for IBM MQ:

  1. Check if you have an ssh key pair in order to access the target machines via Ansible. Go to the ~/.ssh directory in your machine and look for the id_rsa and files.

     cd ~/.ssh
  2. If those two files are not in your ssh directory, you need to generate id_rsa and with the following command:

  3. Once the keys have been generated, these need to be copied to the target machine's user ssh directory.

     ssh-copy-id -i [USER]@[YOUR_TARGET_MACHINE_IP]
  4. To confirm the keys have been copied successfully, connect to your target machine by:


    This should connect to your target machine without asking for a password.

  5. Go to the ansible_collections/ibm/ibmmq/ directory.

     cd ..
     cd ansible_collections/ibm/ibmmq/
  6. Create a file inventory.ini inside the directory with the following content:

    [YOUR_MACHINE_IP] ansible_ssh_user=[YOUR_USER]
    • Change YOUR_TARGET_MACHINES to your machines' group name, for example fyre.
    • Change YOUR_MACHINE_IP to your target machine's public IP
    • Change YOUR_USER to your target machine's user.
    NOTE : user on the target machine MUST NOT be root but MUST have sudo privileges.


The sample playbook ibmmq.yml installs IBM MQ Advanced with our roles and configures a queue manager with the module.

  1. Before running the playbook, ensure that you have added the directory path to the PATH environment variable.

    NOTE : change <PATH-TO> to your local directory path:
    • On Mac:

       export ANSIBLE_LIBRARY=<PATH-TO>/ansible_mq/ansible_collections/ibm/ibmmq/library
    • On Windows:

       set ANSIBLE_LIBRARY=<PATH-TO>/ansible_mq/ansible_collections/ibm/ibmmq/library
  2. Make sure you update the hosts in ibmmq.yml name to YOUR_TARGET_MACHINES group from your inventory file.

  3. Run the following command to execute the tasks within the playbook:

     ansible-playbook ./ibmmq.yml -i inventory.ini -K
    • NOTE : -K will prompt the user to enter the sudo password for [YOUR_USER] on the target machine.
  4. The playbook should return the result of dspmq with the queue manager created listed. Log into your target machine and check it manually:



If one of the following errors appears during the run of the playbook, run the following commands according to the problem:

  • Please add this host's fingerprint to your known_hosts file to manage this host. - Indicates that an SSH password cannot be used instead of a key.


    NOTE : change [YOUR_MACHINE_IP] to the target machine's public IP address
    ssh-keyscan -H [YOUR_MACHINE_IP] >> ~/.ssh/known_hosts
  • zsh: command not found: dspmq - Appears that MQ environment variables have not been set.


    . /opt/mqm/bin/setmqenv -s
  • AMQ7077E: You are not authorized to perform the requested operation - Appears that the user cannot carry out queue manager operations. This occurs when an SSH session to a target machine hasn't been refreshed after the roles have been executed.


    Restart the SSH session.

Testing framework

Testing module's functionality with playbooks

These playbooks test the functionality and performance of our roles and the queue_manager module in Ansible plays.

To run the test playbooks first:

  1. make sure you are in the right directory
     cd tests/playbooks
  2. export the modules to your Ansible library
     export ANSIBLE_LIBRARY=<PATH-TO>/ansible_mq/ansible_collections/ibm/ibmmq/library
    • NOTE : change <PATH-TO> to your local directory path:
  3. run all test playbooks with


Apache 2.0 license


Ansible roles for IBM MQ








No releases published


No packages published