Skip to content


Repository files navigation


📝 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, Redhat, Windows and IBM AIX machines. Our aim is to make MQ-Ansible extensible for other platforms 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.

Playbooks and Roles for IBM MQ installation
Run our sample playbook
Testing Framework
Ansible Galaxy - Installation


  • ansible, passlib and ansible-lint are required on your local machine to run playbooks implementing this collection.
  • a target machine of any of the supported platforms:
    • Ubuntu
    • RedHat
    • Windows
    • IBM AIX
Ansible installation (Installation guide)

Playbooks and Roles for IBM MQ installation on Ubuntu target machines

The playbooks and roles in this collection carry out an installation of IBM MQ Advanced on a target machine. 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 setup and start the web console. Developers can change this file to customise the configuration of their queue managers. Here we use a playbook that calls other playbooks but you can run the roles in playbooks to suit your requirements.

Example Playbooks

ibmmq.yml - this playbook calls the mq-install and mq-setup playbooks, host names are passed into the imported playbook variable as {{ ansible_play_batch }}

- name: Install and setup IBM MQ
  hosts: ['servers']

- name: Run the install playbook
  import_playbook: mq-install.yml

- name: Run the setup playbook
  import_playbook: mq-setup.yml

mq-install.yml - this playbook installs IBM MQ with the SSH user specified in the inventory.

Note: The MQ version and app user's UID and GID can be specified here.
- hosts: "{{ ansible_play_batch }}"
  serial: 1
  become: false
    PATH: /opt/mqm/bin:{{ ansible_env.PATH }}

    - role: setupusers
        app_uid: 909
        app_gid: 909
        mqm_home: /home/mqm
        mqm_profile: .profile
    - role: downloadmq
        version: 930

mq-setup.yml - this playbook sets up IBM MQ using the 'mqm' user

- hosts: "{{ ansible_play_hosts }}"
  serial: 1
  become: yes
  become_user: mqm
    PATH: /opt/mqm/bin:{{ ansible_env.PATH }}

    - getconfig
    - setupconsole
    - startconsole


    - name: Create a queue manager
        - 'QM1'
        - 'QM2'
        state: 'present'

mq-upgrade.yml - this playbook installs an applicable fix pack to an existing MQ installation

- hosts: "{{ ansible_play_batch }}"
  serial: 1
  become: true
    PATH: /opt/mqm/bin:{{ ansible_env.PATH }}

    - role: applyfixpack
        mq_local_path: ~/tmp/


  • setupusers - creates the mqm, admin, and app users; the mqm, mqclient groups; and sets the MQ environment variables. User and group IDs can be specified when calling this role.

  • downloadmq - downloads and unzips the appropriate MQ package based on the target platform to /var/MQServer on the target machine. The MQ version to be installed can be specified when calling this role. You can also specify a local source for the MQ source packages to be copied over to target machine. Example:

    - role: downloadmq
          local_source: true
          mq_local_path: YOUR_PATH

    Where YOUR_PATH is the local path to the MQ source package. Example: /Users/user1/Downloads/mqadv_dev932_ubuntu_x86-64.tar.gz

  • installmq - handles platform-specific installation steps, where Ubuntu machines carry out a Debian installation and RedHat machines carry out an RPM installation. Core MQ components are installed as default, however further components and languages can be be added by uncommenting packages within the package_files list in /roles/installmq/tasks/main.yml:

Note: For Ubuntu, dependencies are sensitive to the order of regex-matched packages in the with_items attribute of the above task.
  • getconfig - copies the dev-config.mqsc file to the target machine. You can also specify a local sourced MQSC file with the var mqsc_local.

  • setupconsole - configures a target machine's environment and permissions to be able to run the MQ Web Console.

  • startconsole - starts the MQ Web Console.

applyfixpack - installs a locally available fix pack to an existing MQ installation. The selected fix pack must be applicable to the MQ version already existing on the target machine.

Modules for IBM MQ resources' configuration

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

Installation roles on Windows machines

Detailed documentation and guide for installing MQ on Windows using our roles can be found here.

Run our sample playbook

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

Before running the playbook and 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 SSH. Go to the ~/.ssh directory in your machine and look for the public and private key files e.g. id_rsa and

     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, you need to copy the public key to the target machine's user ssh directory.

     ssh-copy-id -i [USER]@[YOUR_TARGET_HOST]
  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. On your local machine clone this repository.

  6. Go to the playbooks directory.

     cd playbooks
  7. Create a file inventory.ini inside the directory with the following content:

    YOUR_HOST_ALIAS ansible_host=YOUR_HOSTNAME ansible_ssh_user=YOUR_SSH_USER
    YOUR_HOST_ALIAS ansible_host=YOUR_HOSTNAME ansible_ssh_user=YOUR_SSH_USER
    Note: you can specify one or more hosts
    • Change YOUR_HOST_ALIAS to an alias name that you wish to use e.g. mq-host-1 , you can omit aliases if you prefer
    • Change YOUR_HOSTNAME to your server/hostname, e.g.
    • Change YOUR_SSH_USER to your target machine's SSH user
    Note: the user on the target machine MUST have root or 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 following directory path to the ANSIBLE_LIBRARY environment variable.

    Note: change <PATH-TO> to your local directory path:
    • On Mac:
      export ANSIBLE_LIBRARY=${ANSIBLE_LIBRARY}:<PATH-TO>/mq-ansible/plugins/modules
    • On Windows:
      set ANSIBLE_LIBRARY=%ANSIBLE_LIBRARY%;<PATH-TO>/mq-ansible/plugins/modules
  2. Run the following command to execute the tasks within the playbook:

      ansible-playbook ./ibmmq.yml -i inventory.ini -e 'ibmMqLicence=accept'
    • Note: you can optionally add -K (uppercase) to the command, this will prompt the user to enter the sudo password for [YOUR_SSH_USER] on the target machine, you can omit if you have setup SSH keys
  3. 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_HOST] to the target machine's network address
      ssh-keyscan -H [YOUR_HOST] >> ~/.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. Try the installation with our sample playbook. You should run ibmmq.yml prior.

  2. copy your inventory.ini file to the tests/playbooks directory

  cp inventory.ini tests/playbooks
  1. go to the tests/playbooks directory
  cd tests/playbooks
  1. export the modules to your Ansible library
  export ANSIBLE_LIBRARY=${ANSIBLE_LIBRARY}:<PATH-TO>/mq-ansible/plugins/modules
  • Note: change <PATH-TO> to your local directory path:
  1. run all test playbooks
  ansible-playbook --inventory 'inventory.ini' main_test.yml
  1. if any of the tests fail, run:

       ansible-playbook --inventory 'inventory.ini' cleanup_test.yml

Ansible Galaxy - Installation

  1. First, make sure that you have the minimun required version of ansible core with

    ansible --version
  2. Install the latest version from our github repo with

    ansible-galaxy collection install git+,main

    or the latest version in ansible galaxy with:

    ansible-galaxy collection install ibm_messaging.ibmmq      
  3. In your desired working directory, make sure to create your ansible inventory inventory.ini with the proper target hosts, as you'll refer to them while running the playbook:

  4. Create now a playbook file setup-playbook.yml with the following content to try our roles and modules:

    - name: prepares MQ server
      hosts: mqservers
      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: ../../../playbooks/files/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: queue_manager_12
            state: present

        - name: Use our MQSC File
          become: true
          become_user: mqm
            qmname: queue_manager_12
            state: running
            mqsc_file: /var/mqm/dev-config.mqsc
  1. run it with

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


Apache 2.0 license