Configuration

After installing the IBM z/OSMF collection, you will need ensure that users attempting to utilize the collection have access to z/OSMF on the managed node (LPARs).

Step 1: Directory Structure

The following section discusses configuring the collection … (expand for more)

The following section discusses configuring the collection, it is best to begin by creating the directory structure that will combine the various elements; playbooks, inventory, variables (group_vars & host_vars) as well as environment variables.

In this example, we are using the alternative directory layout that places inventory with group_vars and host_vars which is particularly useful if the variables contained in groups_vars and host_vars don’t have much in common with other systems, eg Linux, Windows, etc.

This directory structure complete with playbook and configurations is available in Ansible Z Playbook Repository.

The directory structure should be created on the control node, that is where Ansible is running.

/playbooks/
        ├── my_playbook.yml       # A playbook
        ├── another_playbook.yml  # Another playbook
        ├── ansible.cfg           # Custom Ansible configuration
        ├── inventories/
            └── host_vars/        # Assign variables to particular systems
                └── zos_host.yml
            └── group_vars/       # Assign variables to particular groups
                └── all.yml
            └── inventory.yml     # Inventory file for production systems

The following commands will also create this directory structure in the /tmp directory.

mkdir -p /tmp/playbooks;
touch /tmp/playbooks/my_playbook.yml;
touch /tmp/playbooks/another_playbook.yml;
touch /tmp/playbooks/ansible.cfg;
mkdir -p /tmp/playbooks/inventories;
mkdir -p /tmp/playbooks/inventories/host_vars;
touch /tmp/playbooks/inventories/host_vars/zos_host.yml;
mkdir -p /tmp/playbooks/inventories/group_vars;
touch /tmp/playbooks/inventories/group_vars/all.yml;
touch /tmp/playbooks/inventories/inventory.yml;

Step 2: Inventory

The following section discusses how Ansible interacts with managed node … (expand for more)

The following section discusses how Ansible interacts with managed nodes (hosts) using a list known as inventory. It is a configuration file that specifies the hosts and group of hosts on which Ansible commands, modules, and playbooks will operate. It also defines variables and connection details for those hosts, such as IP address. For more information, see Building Ansible inventories.

The following inventory is explained.

• systems is a group that contains one managed host, zos1.

• zos1 is the name chosen for managed node, you can choose any name.

• ansible_host is an ansible reserved keyword that is the hostname ansible will connect to and run automated tasks on, it can be an LPAR, ZVM, etc.

• ansible_user is an ansible reserved keyword that is the user Ansible will use to connect to the managed node, generally and OMVS segment.

Edit the file inventory.yml located at /tmp/playbooks/inventories/inventory.yml and paste the following below. You will need to update the properties ansible_host and ansible_user.

systems:
    hosts:
        zos1:
        ansible_host: zos_managed_node_host_name_or_ip
        ansible_user: zos_managed_node_ssh_user

Step 3: User

The following section discusses how the collection connects to the managed node over SSH … (expand for more)

The following section discusses how the collection connects to the managed node using the z/OSMF Web APIs via the zOSMF user defined in inventory or optionally from the command line, thus requiring access to z/OS Management Facility (z/OSMF) as well as access to the additional resources you’re trying to access.

From a security perspective, the collection will require a TSO segment in the users profile. It’s recommended to have an OMVS segment as well.

With the RACF ADDGROUP command you can:

• Define a new group to RACF.

• Add a profile for the new group to the RACF database.

• Specify z/OS UNIX System Services information for the group being defined to RACF.

• specify that RACF is to automatically assign an unused GID value to the group.

With the RACF ADDUSER command you can:

• Define a new user to RACF.

• Add a profile for the new user to the RACF database.

• Create a connect profile that connects the user to the default group.

• Create an OMVS segment.

• Create a TSO segment.

When issuing RACF commands, you might require sufficient authority to the proper resources. It is recommended you review the RACF language reference.

You can define a new group to RACF with command:

ADDGROUP gggggggg OMVS(AUTOGID)

You can add a new user with RACF command:

ADDUSER uuuuuuuu DFLTGRP(gggggggg) OWNER(nnnnnnnn) PASSWORD(pppppppp) TSO(ACCTNUM(aaaaaaaa) PROC(pppppppp)) OMVS(HOME(/u/uuuuuuuu) PROGRAM('/bin/sh')) AUTOUID

To learn more about creating users with RACF, see RACF command syntax.

The following section explains the RACF operands … (expand for more)

The following section explains the RACF operands used in the above RACF commands.

uuuuuuuu

• Specifies the user to be defined to RACF. 1 - 8 alphanumeric characters. A user id can contain any of the supported symbols A-Z, 0-9, #, $, or @.

gggggggg

• Specifies the name of a RACF-defined group to be used as the default group for the user. If you do not specify a group, RACF uses your current connect group as the default. 1 - 8 alphanumeric characters, beginning with an alphabetic character. A group name can contain any of the supported symbols A-Z, 0-9, #, $, or @.

nnnnnnnn

• Specifies a RACF-defined user or group to be assigned as the owner of the new group. If you do not specify an owner, you are defined as the owner of the group.

pppppppp

• Specifies the user’s initial logon password. This password is always set expired, thus requiring the user to change the password at initial logon.

aaaaaaaa

• Specifies the user’s default TSO account number. The account number you specify must be protected by a profile in the ACCTNUM general resource class, and the user must be granted READ access to the profile.

Step 4: Run a playbook

The following section discusses how to run an run an Ansible playbook … (expand for more)

The following section discusses how to use the IBM z/OSMF collection in an Ansible playbook. An Ansible playbook consists of organized instructions that define work for a managed node (host) to be managed with Ansible.

If you have completed steps 1 - 3 above, then you are ready to run a playbook. In the folllowing playbook, there is one task, the task will look for missing critical software updates for a given software instance using ibm_zosmf.zmf_swmgmt_identify_missing_critical_updates

---
- name: Sample of identifying missing critical software updates for a software instance
  hosts: "{{ nodes | default([]) }}"
  gather_facts: false

  tasks:
    - name: Get Missing Critical Updates
      ansible.builtin.include_role:
      name: ibm.ibm_zosmf.zmf_swmgmt_identify_missing_critical_updates

Copy the above playbook into a file, call it sample.yml.

We’re then going to create a variables file to use in conjunction with the sample.yml playbook.

# This variable file serves as a good litmus for configuring the collection.

# The Ansible host where the playbook will execute from.
# The z/OSMF collection is connecting through the z/OSMF REST APIs so localhost is sufficient
# here unless you're combining with other collections.
nodes: "localhost"

# Information needed to connect to z/OSMF
zmf_host: "your.zosmf.instance.url.com"         # z/OSMF Host Name
zmf_port: 0000                                  # z/OSMF Port Number
zmf_user: "demouser"                            # z/OSMF User that will be used for the connection
zmf_password: "password"                        # z/OSMF Password

# Software instance information
software_instance_name: "demo_instance_name"     # Software instance to be updated
system_nickname: "favorite_lpar"                 # The name of the LPAR to be used

# Output file created from this playbook containing missing critical updates response information
missing_critical_updates_response_file: "/user/directory/on/ansible/control/node"

Copy and configure the above variables template into a file, call it variables.yaml.

To run the playbook with the variables file, use the Ansible command ansible-playbook with the inventory you defined.

The command syntax is ansible-playbook -i <inventory> -e @<variables> <playbook>, for example;

ansible-playbook -i inventory -e @variables.yml sample.yaml

Note

• Storing passwords in plain text is not recommended. Use whatever password management strategy is relevant for your company.

• When working with variable files and the -e extra variables flag. When referencing a file the @ symbol is needed. Otherwise ansible will not take in that file full of variables.

You can avoid a password prompt by configuring SSH keys, see setting up SSH keys.

For further reading, review run your first command and playbook and follow up with Ansible playbooks.

Optionally, you can configure the console logging verbosity … (expand for more)

Optionally, you can configure the console logging verbosity during playbook execution. This is helpful in situations where communication is failing and you want to obtain more details. To adjust the logging verbosity, append more letter v’s; for example, -v, -vv, -vvv, or -vvvv. Each letter v increases logging verbosity similar to traditional logging levels INFO, WARN, ERROR, DEBUG.

Using the previous example, the following will set the highest level of verbosity.

ansible-playbook -i inventory -e @variables.yml sample.yaml -vvvv