From 0183773fbfece2cd5766b2ba39913446715859f3 Mon Sep 17 00:00:00 2001 From: Martin Evans Date: Fri, 27 Jan 2023 12:32:11 +0000 Subject: [PATCH 01/15] Split playbook ibmmq into separate playbooks mq-install and mq-setup --- ansible_collections/ibm/ibmmq/ibmmq.yml | 42 +++----------------- ansible_collections/ibm/ibmmq/mq-install.yml | 12 ++++++ ansible_collections/ibm/ibmmq/mq-setup.yml | 35 ++++++++++++++++ 3 files changed, 53 insertions(+), 36 deletions(-) create mode 100644 ansible_collections/ibm/ibmmq/mq-install.yml create mode 100644 ansible_collections/ibm/ibmmq/mq-setup.yml diff --git a/ansible_collections/ibm/ibmmq/ibmmq.yml b/ansible_collections/ibm/ibmmq/ibmmq.yml index 55578a8..9ba15e6 100644 --- a/ansible_collections/ibm/ibmmq/ibmmq.yml +++ b/ansible_collections/ibm/ibmmq/ibmmq.yml @@ -1,38 +1,8 @@ -- hosts: [YOUR_TARGET_MACHINES] - become: false - environment: - PATH: /opt/mqm/bin:{{ ansible_env.PATH }} +- name: Test + hosts: ['servers'] - roles: - - role: setupusers - vars: - gid: 999 - - downloadmq - - installmq - - getconfig - - setupconsole - - startconsole - - tasks: +- name: Run the install playbook + import_playbook: mq-install.yml - - name: Create a queue manager - queue_manager: - qmname: - - 'QM1' - - 'QM2' - state: 'present' - - - name: Start a queue manager - queue_manager: - qmname: - - 'QM1' - - 'QM2' - state: 'running' - - - name: Run MQSC File - queue_manager: - qmname: - - 'QM1' - - 'QM2' - state: 'running' - mqsc_file: '/home/{{ ansible_ssh_user }}/dev-config.mqsc' +- name: Run the setup playbook + import_playbook: mq-setup.yml diff --git a/ansible_collections/ibm/ibmmq/mq-install.yml b/ansible_collections/ibm/ibmmq/mq-install.yml new file mode 100644 index 0000000..85b860e --- /dev/null +++ b/ansible_collections/ibm/ibmmq/mq-install.yml @@ -0,0 +1,12 @@ +- hosts: "{{ ansible_play_batch }}" + serial: 1 + become: false + environment: + PATH: /opt/mqm/bin:{{ ansible_env.PATH }} + + roles: + - role: setupusers + vars: + gid: 909 + - downloadmq + - installmq diff --git a/ansible_collections/ibm/ibmmq/mq-setup.yml b/ansible_collections/ibm/ibmmq/mq-setup.yml new file mode 100644 index 0000000..b1d84ab --- /dev/null +++ b/ansible_collections/ibm/ibmmq/mq-setup.yml @@ -0,0 +1,35 @@ +- hosts: "{{ ansible_play_hosts }}" + serial: 1 + become: yes + become_user: mqm + environment: + PATH: /opt/mqm/bin:{{ ansible_env.PATH }} + + roles: + - getconfig + - setupconsole + - startconsole + + tasks: + + - name: Create a queue manager + queue_manager: + qmname: + - 'QM1' + - 'QM2' + state: 'present' + + - name: Start a queue manager + queue_manager: + qmname: + - 'QM1' + - 'QM2' + state: 'running' + + - name: Run MQSC File + queue_manager: + qmname: + - 'QM1' + - 'QM2' + state: 'running' + mqsc_file: '/var/mqm/dev-config.mqsc' From be6dcb8e6a270487168ad23fce0160fb5b8c21e4 Mon Sep 17 00:00:00 2001 From: Martin Evans Date: Fri, 27 Jan 2023 12:34:23 +0000 Subject: [PATCH 02/15] Copying MQSC file to /var/mqm instead of SSH user home folder --- ansible_collections/ibm/ibmmq/roles/getconfig/tasks/main.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ansible_collections/ibm/ibmmq/roles/getconfig/tasks/main.yml b/ansible_collections/ibm/ibmmq/roles/getconfig/tasks/main.yml index 7d4f778..20c6fa8 100644 --- a/ansible_collections/ibm/ibmmq/roles/getconfig/tasks/main.yml +++ b/ansible_collections/ibm/ibmmq/roles/getconfig/tasks/main.yml @@ -3,4 +3,4 @@ - name: Copy developer config file to target copy: src: ../../../dev-config.mqsc - dest: "/home/{{ ansible_ssh_user }}" + dest: "/var/mqm" From bf69bf3c46416df917d53e7a916e25051296d274 Mon Sep 17 00:00:00 2001 From: Martin Evans Date: Fri, 27 Jan 2023 12:35:37 +0000 Subject: [PATCH 03/15] Simplified moving of example XML file and removed backup of existing --- .../ibmmq/roles/setupconsole/tasks/main.yml | 43 +++++-------------- 1 file changed, 11 insertions(+), 32 deletions(-) diff --git a/ansible_collections/ibm/ibmmq/roles/setupconsole/tasks/main.yml b/ansible_collections/ibm/ibmmq/roles/setupconsole/tasks/main.yml index 734a00f..e4e767f 100644 --- a/ansible_collections/ibm/ibmmq/roles/setupconsole/tasks/main.yml +++ b/ansible_collections/ibm/ibmmq/roles/setupconsole/tasks/main.yml @@ -1,46 +1,25 @@ --- -- name: Check if basic registry exists +- name: Check if basic registry exists in the install folder stat: path: /opt/mqm/web/mq/samp/configuration/basic_registry.xml register: basic_registry_result -- name: Moving basic registry - become: true - shell: mv /opt/mqm/web/mq/samp/configuration/basic_registry.xml /var/mqm/web/installations/Installation1/servers/mqweb/ - when: basic_registry_result.stat.exists - -- name: Check if old mqwebuser exists +- name: Check if mqwebuser already exists in target folder stat: - path: /var/mqm/web/installations/Installation1/servers/mqweb/mqwebuser.old - register: mqwebuser_result + path: /var/mqm/web/installations/Installation1/servers/mqweb/mqwebuser.xml + register: target_mqwebuser_result -- name: moving mqwebuser to old mqwebuser +- name: Set permissions to allow overwrite of target mqwebuser.xml if it already exists become: true - shell: mv /var/mqm/web/installations/Installation1/servers/mqweb/mqwebuser.xml /var/mqm/web/installations/Installation1/servers/mqweb/mqwebuser.old - when: not mqwebuser_result.stat.exists - -- name: Check if moved basic registry exists - stat: - path: /var/mqm/web/installations/Installation1/servers/mqweb/basic_registry.xml - register: moved_registry + shell: chmod 640 /var/mqm/web/installations/Installation1/servers/mqweb/mqwebuser.xml + when: target_mqwebuser_result.stat.exists -- name: Using basic_registry as webwebuser +- name: Copying basic registry become: true - shell: mv /var/mqm/web/installations/Installation1/servers/mqweb/basic_registry.xml /var/mqm/web/installations/Installation1/servers/mqweb/mqwebuser.xml - when: moved_registry.stat.exists - -- name: Check correct mqwebuser exists - stat: - path: /var/mqm/web/installations/Installation1/servers/mqweb/mqwebuser.xml - register: final_mqwebuser + shell: cp /opt/mqm/web/mq/samp/configuration/basic_registry.xml /var/mqm/web/installations/Installation1/servers/mqweb/mqwebuser.xml + when: basic_registry_result.stat.exists -- name: ensure correct permissions for mqwebuser.xml +- name: ensure correct permissions for mqwebuser.xml to allow setmqweb commands become: true shell: chmod 640 /var/mqm/web/installations/Installation1/servers/mqweb/mqwebuser.xml - when: final_mqwebuser.stat.exists - -- name: ensure correct permissions for mqwebuser.xml - become: true - shell: chown {{ ansible_ssh_user }} /var/mqm/web/installations/Installation1/servers/mqweb/mqwebuser.xml - when: final_mqwebuser.stat.exists From 8449cde531434318e883f9756588a642cf3f511c Mon Sep 17 00:00:00 2001 From: Martin Evans Date: Fri, 27 Jan 2023 12:44:37 +0000 Subject: [PATCH 04/15] Added meaningful name to main playbook --- ansible_collections/ibm/ibmmq/ibmmq.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ansible_collections/ibm/ibmmq/ibmmq.yml b/ansible_collections/ibm/ibmmq/ibmmq.yml index 9ba15e6..d57a341 100644 --- a/ansible_collections/ibm/ibmmq/ibmmq.yml +++ b/ansible_collections/ibm/ibmmq/ibmmq.yml @@ -1,4 +1,4 @@ -- name: Test +- name: Install and setup IBM MQ hosts: ['servers'] - name: Run the install playbook From 96c9da0d8e9147f5c0cd60ba490c969d5d2143bc Mon Sep 17 00:00:00 2001 From: Martin Evans Date: Tue, 31 Jan 2023 17:34:07 +0000 Subject: [PATCH 05/15] Changing tests to match changes in roles for target location of MQSC file --- .../ibm/ibmmq/tests/playbooks/ibmmq_travis.yml | 2 +- .../ibm/ibmmq/tests/playbooks/test_install.yml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/ansible_collections/ibm/ibmmq/tests/playbooks/ibmmq_travis.yml b/ansible_collections/ibm/ibmmq/tests/playbooks/ibmmq_travis.yml index c3ff589..55c8087 100644 --- a/ansible_collections/ibm/ibmmq/tests/playbooks/ibmmq_travis.yml +++ b/ansible_collections/ibm/ibmmq/tests/playbooks/ibmmq_travis.yml @@ -35,5 +35,5 @@ - 'QM1' - 'QM2' state: 'running' - mqsc_file: '/home/{{ ansible_ssh_user }}/dev-config.mqsc' + mqsc_file: '/var/mqm/dev-config.mqsc' diff --git a/ansible_collections/ibm/ibmmq/tests/playbooks/test_install.yml b/ansible_collections/ibm/ibmmq/tests/playbooks/test_install.yml index e508161..211651e 100644 --- a/ansible_collections/ibm/ibmmq/tests/playbooks/test_install.yml +++ b/ansible_collections/ibm/ibmmq/tests/playbooks/test_install.yml @@ -66,10 +66,10 @@ - name: get dev config stat: - path: "/home/{{ ansible_ssh_user }}/dev-config.mqsc" + path: "/var/mqm/dev-config.mqsc" register: testout_dev_config_copied - name: test dev config exists assert: that: testout_dev_config_copied.stat.exists - \ No newline at end of file + From e0c6b694ff5cb259bf23bd837fd57498122cea11 Mon Sep 17 00:00:00 2001 From: Martin Evans Date: Tue, 31 Jan 2023 17:55:58 +0000 Subject: [PATCH 06/15] Changed to reflect enhancements --- README.md | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index a50ff25..b00ac72 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ | :memo: | Interested in contributing to this project? Please read our [IBM Contributor License Agreement](CLA.md) and our [Contributing Guide](CONTRIBUTING.md). | |---------------|:------------------------| -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. +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 other platforms and more detailed IBM MQ configuration. This directory contains: - ansible [`roles`](https://github.com/ibm-messaging/mq-ansible/tree/main/ansible_collections/ibm/ibmmq/roles) for the installation and configuration of IBM MQ. @@ -19,7 +19,7 @@ For a detailed explanation and documentation on how MQ-Ansible works, click [her ## 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. +The roles in this collection carryout an installation of IBM MQ Advanced on an Ubuntu 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 allow better configuration of their queue managers. ### Example @@ -89,14 +89,16 @@ Before running the playbook implementing our modules and roles for IBM MQ: 6. Create a file `inventory.ini` inside the directory with the following content: ```ini - [YOUR_TARGET_MACHINES] - [YOUR_MACHINE_IP] ansible_ssh_user=[YOUR_USER] - ``` + + [servers] + server-alias-n ansible_host=[YOUR_HOSTNAME_n] ansible_ssh_user=[YOUR_SSH_USER] + server-alias-n ansible_host=[YOUR_HOSTNAME_n] ansible_ssh_user=[YOUR_SSH_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. + ``` + - Change each `server-alias-n` to an alias name that you wish to use + - Change each `YOUR_HOSTNAME_n` to your server/hostname, for example: `myserver-1.fyre.com`. + - Change `YOUR_SSH_USER` to your target machine's SSH user. + ##### *NOTE* : the user on the target machine MUST have `sudo` privileges. ### ibmmq.yml @@ -109,13 +111,13 @@ The sample playbook [`ibmmq.yml`](ansible_collections/ibm/ibmmq/ibmmq.yml) insta - On Mac: ```shell - export ANSIBLE_LIBRARY=/ansible_mq/ansible_collections/ibm/ibmmq/library + export ANSIBLE_LIBRARY=${ANSIBLE_LIBRARY}:/ansible_mq/ansible_collections/ibm/ibmmq/library ``` - On Windows: ```shell - set ANSIBLE_LIBRARY=/ansible_mq/ansible_collections/ibm/ibmmq/library + set ANSIBLE_LIBRARY=%ANSIBLE_LIBRARY%;/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. @@ -173,7 +175,7 @@ To run the test playbooks first: export ANSIBLE_LIBRARY=/ansible_mq/ansible_collections/ibm/ibmmq/library ``` - ##### *NOTE* : change `` to your local directory path: -3. run all test playbooks with `main.py` +3. run all test playbooks with `python3 main.py` ## License From 0d4b6a2b401d66dbc21ea404b13c834b17bb6b39 Mon Sep 17 00:00:00 2001 From: Martin Evans Date: Tue, 31 Jan 2023 18:06:45 +0000 Subject: [PATCH 07/15] Changed to reflect enhancements --- README.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index b00ac72..f17ed68 100644 --- a/README.md +++ b/README.md @@ -120,15 +120,13 @@ The sample playbook [`ibmmq.yml`](ansible_collections/ibm/ibmmq/ibmmq.yml) insta set ANSIBLE_LIBRARY=%ANSIBLE_LIBRARY%;/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: +2. Run the following command to execute the tasks within the playbook: ```shell - ansible-playbook ./ibmmq.yml -i inventory.ini -K + 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. + - ##### *NOTE* : `-K` 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. -4. The playbook should return the result of `dspmq` with the queue manager created listed. Log into your target machine and check it manually: +3. The playbook should return the result of `dspmq` with the queue manager created listed. Log into your target machine and check it manually: ```shell dspmq From c611ab221cd388c859528699ec217ed1e8893a95 Mon Sep 17 00:00:00 2001 From: Martin Evans Date: Wed, 1 Feb 2023 10:03:13 +0000 Subject: [PATCH 08/15] Documentation updated to reflect changes to playbooks --- README.md | 78 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 56 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index f17ed68..f2870e6 100644 --- a/README.md +++ b/README.md @@ -17,41 +17,74 @@ For a detailed explanation and documentation on how MQ-Ansible works, click [her - `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 +## Playbooks and Roles for IBM MQ installation -The roles in this collection carryout an installation of IBM MQ Advanced on an Ubuntu 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 allow better configuration of their queue managers. +The playbooks and roles in this collection carryout an installation of IBM MQ Advanced on an Ubuntu 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 -### Example +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 }} ```yaml -- hosts: [YOUR_TARGET_MACHINES] +- 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 + +```yaml +- hosts: "{{ ansible_play_batch }}" + serial: 1 become: false environment: PATH: /opt/mqm/bin:{{ ansible_env.PATH }} - roles: + roles: - role: setupusers vars: - gid: 989 + gid: 909 - downloadmq - installmq +``` +mq-setup.yml - this playbook sets up IBM MQ using the 'mqm' user + +```yaml +- hosts: "{{ ansible_play_hosts }}" + serial: 1 + become: yes + become_user: mqm + environment: + PATH: /opt/mqm/bin:{{ ansible_env.PATH }} + + roles: - getconfig - setupconsole - startconsole -``` + tasks: + + - name: Create a queue manager + queue_manager: + qmname: + - 'QM1' + - 'QM2' + state: 'present' +``` ## Modules for IBM MQ resources' configuration - `queue_manager.py`- Creates, starts, deletes an IBM MQ queue manager and runs an MQSC file. See the documentation [here.](QUEUE_MANAGER.md) # Run our sample playbook -### Setup (inventory.ini) - ##### Note: *Ansible* must be installed on the local machine. ([Installation guide](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)) -Before running the playbook implementing our modules and roles for IBM MQ: +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 Ansible. Go to the `~/.ssh` directory in your machine and look for the `id_rsa` and `id_rsa.pub` files. @@ -68,13 +101,13 @@ Before running the playbook implementing our modules and roles for IBM MQ: 3. Once the keys have been generated, these need to be copied to the target machine's user `ssh` directory. ```shell - ssh-copy-id -i id_rsa.pub [USER]@[YOUR_TARGET_MACHINE_IP] + ssh-copy-id -i id_rsa.pub [USER]@[YOUR_TARGET_HOST] ``` 4. To confirm the keys have been copied successfully, connect to your target machine by: ```shell - ssh [USER]@[YOUR_TARGET_MACHINE_IP] + ssh [USER]@[YOUR_TARGET_HOST] ``` This should connect to your target machine without asking for a password. @@ -91,20 +124,21 @@ Before running the playbook implementing our modules and roles for IBM MQ: ```ini [servers] - server-alias-n ansible_host=[YOUR_HOSTNAME_n] ansible_ssh_user=[YOUR_SSH_USER] - server-alias-n ansible_host=[YOUR_HOSTNAME_n] ansible_ssh_user=[YOUR_SSH_USER] + 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 ``` - - Change each `server-alias-n` to an alias name that you wish to use - - Change each `YOUR_HOSTNAME_n` to your server/hostname, for example: `myserver-1.fyre.com`. - - Change `YOUR_SSH_USER` to your target machine's SSH user. - ##### *NOTE* : the user on the target machine MUST have `sudo` privileges. + :information_source: 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. `myserver-1.fyre.com` + - Change `YOUR_SSH_USER` to your target machine's SSH user + ##### *NOTE* : the user on the target machine MUST have `root` or `sudo` privileges. ### ibmmq.yml The sample playbook [`ibmmq.yml`](ansible_collections/ibm/ibmmq/ibmmq.yml) installs IBM MQ Advanced with our roles and configures a queue manager with the `queue_manager.py` module. -1. Before running the playbook, ensure that you have added the directory path to the PATH environment variable. +1. Before running the playbook, ensure that you have added the following directory path to the ANSIBLE_LIBRARY environment variable. ##### *NOTE* : change `` to your local directory path: @@ -124,7 +158,7 @@ The sample playbook [`ibmmq.yml`](ansible_collections/ibm/ibmmq/ibmmq.yml) insta ```shell ansible-playbook ./ibmmq.yml -i inventory.ini [-K] ``` - - ##### *NOTE* : `-K` 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. + - ##### *NOTE* : The optional `-K` 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: @@ -139,9 +173,9 @@ If one of the following errors appears during the run of the playbook, run the f - `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. Fix: - ##### *NOTE* : change `[YOUR_MACHINE_IP]` to the target machine's public IP address + ##### *NOTE* : change `[YOUR_HOST]` to the target machine's network address ```shell - ssh-keyscan -H [YOUR_MACHINE_IP] >> ~/.ssh/known_hosts + ssh-keyscan -H [YOUR_HOST] >> ~/.ssh/known_hosts ``` - `zsh: command not found: dspmq` - Appears that MQ environment variables have not been set. From 62c1030229a66c98e9ee55de19c49613991fa109 Mon Sep 17 00:00:00 2001 From: Martin Evans Date: Wed, 1 Feb 2023 10:13:15 +0000 Subject: [PATCH 09/15] Documentation updated to make note format consistent --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index f2870e6..d6f89d0 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,7 @@ mq-setup.yml - this playbook sets up IBM MQ using the 'mqm' user # Run our sample playbook -##### Note: *Ansible* must be installed on the local machine. ([Installation guide](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)) +##### *Note*: *Ansible* must be installed on the local machine. ([Installation guide](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)) Before running the playbook and implementing our modules and roles for IBM MQ: @@ -128,11 +128,11 @@ Before running the playbook and implementing our modules and roles for IBM MQ: YOUR_HOST_ALIAS ansible_host=YOUR_HOSTNAME ansible_ssh_user=YOUR_SSH_USER ``` - :information_source: Note: You can specify one or more hosts. + ##### *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. `myserver-1.fyre.com` - Change `YOUR_SSH_USER` to your target machine's SSH user - ##### *NOTE* : the user on the target machine MUST have `root` or `sudo` privileges. + ##### *Note*: the user on the target machine MUST have `root` or `sudo` privileges. ### ibmmq.yml @@ -140,7 +140,7 @@ The sample playbook [`ibmmq.yml`](ansible_collections/ibm/ibmmq/ibmmq.yml) insta 1. Before running the playbook, ensure that you have added the following directory path to the ANSIBLE_LIBRARY environment variable. - ##### *NOTE* : change `` to your local directory path: + ##### *NOTE*: change `` to your local directory path: - On Mac: @@ -158,7 +158,7 @@ The sample playbook [`ibmmq.yml`](ansible_collections/ibm/ibmmq/ibmmq.yml) insta ```shell ansible-playbook ./ibmmq.yml -i inventory.ini [-K] ``` - - ##### *NOTE* : The optional `-K` 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. + - ##### *Note*: The optional `-K` 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: @@ -173,7 +173,7 @@ If one of the following errors appears during the run of the playbook, run the f - `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. Fix: - ##### *NOTE* : change `[YOUR_HOST]` to the target machine's network address + :information_source: ##### *Note*: change `[YOUR_HOST]` to the target machine's network address ```shell ssh-keyscan -H [YOUR_HOST] >> ~/.ssh/known_hosts ``` @@ -206,7 +206,7 @@ To run the test playbooks first: ```shell export ANSIBLE_LIBRARY=/ansible_mq/ansible_collections/ibm/ibmmq/library ``` - - ##### *NOTE* : change `` to your local directory path: + - ##### *Note*: change `` to your local directory path: 3. run all test playbooks with `python3 main.py` ## License From 4ad5ca0139a44b09f2d266bb6c55be5a5638d41a Mon Sep 17 00:00:00 2001 From: Martin Evans Date: Wed, 1 Feb 2023 10:18:16 +0000 Subject: [PATCH 10/15] Documentation updated to make note format consistent --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index d6f89d0..1b98cbc 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,7 @@ mq-setup.yml - this playbook sets up IBM MQ using the 'mqm' user # Run our sample playbook -##### *Note*: *Ansible* must be installed on the local machine. ([Installation guide](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)) +##### *Note*: *Ansible* must be installed on the local machine ([Installation guide](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)) Before running the playbook and implementing our modules and roles for IBM MQ: @@ -128,11 +128,11 @@ Before running the playbook and implementing our modules and roles for IBM MQ: YOUR_HOST_ALIAS ansible_host=YOUR_HOSTNAME ansible_ssh_user=YOUR_SSH_USER ``` - ##### *Note*: You can specify one or more hosts. + ##### *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. `myserver-1.fyre.com` - Change `YOUR_SSH_USER` to your target machine's SSH user - ##### *Note*: the user on the target machine MUST have `root` or `sudo` privileges. + ##### *Note*: the user on the target machine MUST have `root` or `sudo` privileges ### ibmmq.yml @@ -158,7 +158,7 @@ The sample playbook [`ibmmq.yml`](ansible_collections/ibm/ibmmq/ibmmq.yml) insta ```shell ansible-playbook ./ibmmq.yml -i inventory.ini [-K] ``` - - ##### *Note*: The optional `-K` 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. + - ##### *Note*: the optional `-K` 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: @@ -173,7 +173,7 @@ If one of the following errors appears during the run of the playbook, run the f - `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. Fix: - :information_source: ##### *Note*: change `[YOUR_HOST]` to the target machine's network address + ##### *Note*: change `[YOUR_HOST]` to the target machine's network address ```shell ssh-keyscan -H [YOUR_HOST] >> ~/.ssh/known_hosts ``` From b7510e586c8c52a4839a719d62e70f327fa19f86 Mon Sep 17 00:00:00 2001 From: Martin Evans Date: Wed, 1 Feb 2023 10:26:54 +0000 Subject: [PATCH 11/15] Documentation - fix shell sections --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 1b98cbc..b7b388b 100644 --- a/README.md +++ b/README.md @@ -144,15 +144,15 @@ The sample playbook [`ibmmq.yml`](ansible_collections/ibm/ibmmq/ibmmq.yml) insta - On Mac: - ```shell - export ANSIBLE_LIBRARY=${ANSIBLE_LIBRARY}:/ansible_mq/ansible_collections/ibm/ibmmq/library - ``` + ```shell + export ANSIBLE_LIBRARY=${ANSIBLE_LIBRARY}:/ansible_mq/ansible_collections/ibm/ibmmq/library + ``` - - On Windows: - - ```shell - set ANSIBLE_LIBRARY=%ANSIBLE_LIBRARY%;/ansible_mq/ansible_collections/ibm/ibmmq/library - ``` + - On Windows: + + ```shell + set ANSIBLE_LIBRARY=%ANSIBLE_LIBRARY%;/ansible_mq/ansible_collections/ibm/ibmmq/library + ``` 2. Run the following command to execute the tasks within the playbook: ```shell From d748fd19eedc167263bb7e27bf3ea832eba97b78 Mon Sep 17 00:00:00 2001 From: Martin Evans Date: Wed, 1 Feb 2023 13:48:33 +0000 Subject: [PATCH 12/15] Documentation - minor changes, added to prereqs --- README.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index b7b388b..bcdc4f7 100644 --- a/README.md +++ b/README.md @@ -14,9 +14,11 @@ For a detailed explanation and documentation on how MQ-Ansible works, click [her ## Requirements -- `ansible` and `ansible-lint` are required on your local machine to run playbooks implementing this collection. +- `ansible`, `passlib` and `ansible-lint` are required on your local machine to run playbooks implementing this collection. - An Ubuntu target machine is required to run MQ. + ##### *Ansible* installation ([Installation guide](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)) + ## Playbooks and Roles for IBM MQ installation The playbooks and roles in this collection carryout an installation of IBM MQ Advanced on an Ubuntu 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. @@ -86,7 +88,7 @@ mq-setup.yml - this playbook sets up IBM MQ using the 'mqm' user 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 Ansible. Go to the `~/.ssh` directory in your machine and look for the `id_rsa` and `id_rsa.pub` files. +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 `id_rsa.pub`. ```shell cd ~/.ssh @@ -111,15 +113,16 @@ Before running the playbook and implementing our modules and roles for IBM MQ: ``` This should connect to your target machine without asking for a password. -5. Go to the `ansible_collections/ibm/ibmmq/` directory. +5. On your local machine clone this repository. + +6. Go to the `ansible_collections/ibm/ibmmq/` directory. ```shell - cd .. - cd ansible_collections/ibm/ibmmq/ + cd mq-ansible/ansible_collections/ibm/ibmmq/ ``` -6. Create a file `inventory.ini` inside the directory with the following content: +7. Create a file `inventory.ini` inside the directory with the following content: ```ini @@ -140,7 +143,7 @@ The sample playbook [`ibmmq.yml`](ansible_collections/ibm/ibmmq/ibmmq.yml) insta 1. Before running the playbook, ensure that you have added the following directory path to the ANSIBLE_LIBRARY environment variable. - ##### *NOTE*: change `` to your local directory path: + ##### *Note*: change `` to your local directory path: - On Mac: @@ -156,9 +159,9 @@ The sample playbook [`ibmmq.yml`](ansible_collections/ibm/ibmmq/ibmmq.yml) insta 2. Run the following command to execute the tasks within the playbook: ```shell - ansible-playbook ./ibmmq.yml -i inventory.ini [-K] + ansible-playbook ./ibmmq.yml -i inventory.ini ``` - - ##### *Note*: the optional `-K` 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 + - ##### *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: From 013cb10a10ecd93eb32fb0e1d3a93faacf84aaaf Mon Sep 17 00:00:00 2001 From: Martin Evans Date: Thu, 2 Feb 2023 14:26:41 +0000 Subject: [PATCH 13/15] Added tags to download tasks, created user mqadm --- .../ibm/ibmmq/roles/downloadmq/tasks/main.yml | 4 +++- .../ibm/ibmmq/roles/setupusers/tasks/main.yml | 6 ++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/ansible_collections/ibm/ibmmq/roles/downloadmq/tasks/main.yml b/ansible_collections/ibm/ibmmq/roles/downloadmq/tasks/main.yml index 2061f5a..f12a774 100644 --- a/ansible_collections/ibm/ibmmq/roles/downloadmq/tasks/main.yml +++ b/ansible_collections/ibm/ibmmq/roles/downloadmq/tasks/main.yml @@ -5,9 +5,11 @@ url: https://public.dhe.ibm.com/ibmdl/export/pub/software/websphere/messaging/mqadv/mqadv_dev920_ubuntu_x86-64.tar.gz dest: /tmp/mq.tar.gz force: no + tags: download - name: Extract MQ fom TAR unarchive: src: /tmp/mq.tar.gz remote_src: yes - dest: /tmp \ No newline at end of file + dest: /tmp + tags: download \ No newline at end of file diff --git a/ansible_collections/ibm/ibmmq/roles/setupusers/tasks/main.yml b/ansible_collections/ibm/ibmmq/roles/setupusers/tasks/main.yml index f471aae..7f0a3a3 100644 --- a/ansible_collections/ibm/ibmmq/roles/setupusers/tasks/main.yml +++ b/ansible_collections/ibm/ibmmq/roles/setupusers/tasks/main.yml @@ -16,3 +16,9 @@ password: "{{ 'apppassword' | password_hash('sha512', 65534 | random(seed=inventory_hostname) | string) }}" uid: "{{ gid }}" group: mqclient + +- name: Create an admin user + user: + name: mqadm + groups: mqm + append: yes From 346492abe8be56797b205ab6ebb0ada74552526a Mon Sep 17 00:00:00 2001 From: Martin Evans Date: Thu, 2 Feb 2023 14:27:42 +0000 Subject: [PATCH 14/15] Fixed copy SSH key instructions - must not copy private key --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index bcdc4f7..ebc0bf8 100644 --- a/README.md +++ b/README.md @@ -100,7 +100,7 @@ Before running the playbook and implementing our modules and roles for IBM MQ: ssh-keygen ``` -3. Once the keys have been generated, these need to be copied to the target machine's user `ssh` directory. +3. Once the keys have been generated, you need to copy the public key to the target machine's user `ssh` directory. ```shell ssh-copy-id -i id_rsa.pub [USER]@[YOUR_TARGET_HOST] @@ -207,7 +207,7 @@ To run the test playbooks first: ``` 2. export the modules to your Ansible library ```shell - export ANSIBLE_LIBRARY=/ansible_mq/ansible_collections/ibm/ibmmq/library + export ANSIBLE_LIBRARY=${ANSIBLE_LIBRARY}:/ansible_mq/ansible_collections/ibm/ibmmq/library ``` - ##### *Note*: change `` to your local directory path: 3. run all test playbooks with `python3 main.py` From a6fd6ac71d62d53b2679ff018c33483bfcf43988 Mon Sep 17 00:00:00 2001 From: Martin Evans Date: Fri, 3 Feb 2023 12:55:26 +0000 Subject: [PATCH 15/15] Added create mqm user and group to setup users, changed IBM MQ version to 9.3.1 --- ansible_collections/ibm/ibmmq/mq-install.yml | 3 +- .../ibm/ibmmq/roles/downloadmq/tasks/main.yml | 2 +- .../ibm/ibmmq/roles/installmq/tasks/main.yml | 11 ------- .../ibmmq/roles/setupusers/defaults/main.yml | 5 +++- .../ibm/ibmmq/roles/setupusers/tasks/main.yml | 30 ++++++++++++++----- 5 files changed, 29 insertions(+), 22 deletions(-) diff --git a/ansible_collections/ibm/ibmmq/mq-install.yml b/ansible_collections/ibm/ibmmq/mq-install.yml index 85b860e..86406a4 100644 --- a/ansible_collections/ibm/ibmmq/mq-install.yml +++ b/ansible_collections/ibm/ibmmq/mq-install.yml @@ -7,6 +7,7 @@ roles: - role: setupusers vars: - gid: 909 + appUid: 909 + appGid: 909 - downloadmq - installmq diff --git a/ansible_collections/ibm/ibmmq/roles/downloadmq/tasks/main.yml b/ansible_collections/ibm/ibmmq/roles/downloadmq/tasks/main.yml index f12a774..aa4cb08 100644 --- a/ansible_collections/ibm/ibmmq/roles/downloadmq/tasks/main.yml +++ b/ansible_collections/ibm/ibmmq/roles/downloadmq/tasks/main.yml @@ -2,7 +2,7 @@ - name: Download MQ Advanced for Developers get_url: - url: https://public.dhe.ibm.com/ibmdl/export/pub/software/websphere/messaging/mqadv/mqadv_dev920_ubuntu_x86-64.tar.gz + url: https://public.dhe.ibm.com/ibmdl/export/pub/software/websphere/messaging/mqadv/mqadv_dev931_ubuntu_x86-64.tar.gz dest: /tmp/mq.tar.gz force: no tags: download diff --git a/ansible_collections/ibm/ibmmq/roles/installmq/tasks/main.yml b/ansible_collections/ibm/ibmmq/roles/installmq/tasks/main.yml index 0ee915f..8487d6e 100644 --- a/ansible_collections/ibm/ibmmq/roles/installmq/tasks/main.yml +++ b/ansible_collections/ibm/ibmmq/roles/installmq/tasks/main.yml @@ -44,17 +44,6 @@ apt-get update changed_when: 'installed_mq_packages.stdout_lines | string is not search("ibmmq")' -- name: Add the user to group mqm - become: true - shell: adduser ${SUDO_USER:-${USER}} mqm - -- name: Add the user to group mqm - become: true - user: - name: "{{ ansible_ssh_user }}" - groups: mqm - append: yes - - name: reset ssh connection meta: reset_connection diff --git a/ansible_collections/ibm/ibmmq/roles/setupusers/defaults/main.yml b/ansible_collections/ibm/ibmmq/roles/setupusers/defaults/main.yml index 29fe08b..ffc7956 100644 --- a/ansible_collections/ibm/ibmmq/roles/setupusers/defaults/main.yml +++ b/ansible_collections/ibm/ibmmq/roles/setupusers/defaults/main.yml @@ -1,3 +1,6 @@ --- -gid: 989 \ No newline at end of file +appUid: 909 +appGid: 909 +mqmUid: 2001 +mqmGid: 2001 \ No newline at end of file diff --git a/ansible_collections/ibm/ibmmq/roles/setupusers/tasks/main.yml b/ansible_collections/ibm/ibmmq/roles/setupusers/tasks/main.yml index 7f0a3a3..bebf6bb 100644 --- a/ansible_collections/ibm/ibmmq/roles/setupusers/tasks/main.yml +++ b/ansible_collections/ibm/ibmmq/roles/setupusers/tasks/main.yml @@ -1,11 +1,28 @@ --- +- name: Create mqm group + group: + name: mqm + gid: "{{ mqmGid }}" + +- name: Create mqm user + user: + name: mqm + uid: "{{ mqmUid }}" + group: mqm + +- name: Create an admin user + user: + name: mqadm + groups: mqm + append: yes + - name: Add 'mqclient' group become: true group: name: mqclient state: present - gid: "{{ gid }}" + gid: "{{ appGid }}" - name: Add the user 'app' with a specific UID become: true @@ -14,11 +31,8 @@ user: name: app password: "{{ 'apppassword' | password_hash('sha512', 65534 | random(seed=inventory_hostname) | string) }}" - uid: "{{ gid }}" + uid: "{{ appUid }}" group: mqclient - -- name: Create an admin user - user: - name: mqadm - groups: mqm - append: yes + + +