Merge branch 'main' into enabler/1618/create_gdg_playbooks_into_respo…

…sitory

README.md

@@ -47,6 +47,7 @@ often repeated and in need of automation.
   - [Set Up Ansible Host Variables for Python and ZOAU](zos_administration/host_setup)
   - [Manage z/OS Users Using Ansible](zos_concepts/user_management/add_remove_user) - \[[Playback](https://mediacenter.ibm.com/media/Managing+z+OS+Users+with+Ansible+/1_bnud4enw)]
   - [Ansible Fact Gathering for z/OS](zos_basics/factgathering)
+  - [Unarchive Pax and Set Custom Facts](zos_basics/unarchive_pax_and_set_custom_facts)
   - [Synchronize APF authorized libraries from a configuration cloned from GitHub](zos_concepts/program_authorization/git_apf) - \[[Playback](https://mediacenter.ibm.com/media/Using+Ansible+to+synchronize+z+OS+APF+libraries+from+a+GitHub+configuration+file/1_e6qsiwmg)]
   - [Manage z/OS Certificates](zos_concepts/certificate_management#readme)
 - Basic Operations
@@ -143,7 +144,7 @@ For further reading on how playbook projects are organized in this repository,
 review the following [documentation](./docs/share/contribution-guidelines.md#playbook-structure).
 
 ## Copyright
-© Copyright IBM Corporation 2020 - 2023
+© Copyright IBM Corporation 2020 - 2024
 
 ## License
 Licensed under

zos_basics/unarchive_pax_and_set_custom_facts/README.md

@@ -0,0 +1,74 @@
+# Unarchive Pax and Set Custom Facts for z/OS
+
+These sample playbooks demonstrate how to unpackage and install a z/OS program
+from a pax file on a remote system and how to access and update custom Ansible
+facts with Red Hat Ansible Certified Content for IBM Z and built in Red Hat
+Ansible features.
+
+
+These playbooks use:
+  - collection:
+    - ibm.ibm_zos_core
+  - modules:
+    - zos_copy
+    - zos_unarchive
+
+
+It is a good practice to review the playbook contents before executing
+them. It will help you understand the requirements in terms of space, location,
+names, authority, and the artifacts that will be created and cleaned up.
+
+
+## Playbook Requirements
+This playbook requires:
+
+- [IBM® z/OS® core collection 1.10.0 or later](https://galaxy.ansible.com/ibm/ibm_zos_core)
+- [Ansible® 2.14 or later](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)
+
+
+## Configuration
+- Configure the included [inventory.yml](inventories/inventory.yml) with the
+  information from the managed z/OS host.
+  - Review [inventory documentation](../../../docs/share/zos_core/configure_inventory.md)
+- Configure the included **host_vars** [zos_host.yml](inventories/host_vars/zos_host.yml)
+  with the information from your z/OS system.
+  - Review [host_vars documentation](../../../docs/share/zos_core/configure_host_vars.md)
+    and any additional noted variables in the configuration.
+
+
+## Run the playbook
+This project has included a `site.yml` playbook that serves as the primary playbook
+that provides additional prerequisite checks then it invokes the three included playbooks
+`copy_sample_facts_files_to_remote_system.yml`, `gather_and_print_facts.yml` and `unarchive_pax_and_set_custom_facts.yml`
+
+If you want to run the primary playbook `site.yml` it will check that your environment
+has the correct version of Ansible as well as the collection needed to execute
+correctly. To run the primary playbook, use command:
+
+```bash
+ansible-playbook -i inventories site.yml
+```
+
+You can skip the prerequisite check and run the included playbooks with
+command:
+
+```bash
+ansible-playbook -i inventories copy_sample_facts_files_to_remote_system.yml
+ansible-playbook -i inventories gather_and_print_facts.yml
+ansible-playbook -i inventories unarchive_pax_and_set_custom_facts.yml
+```
+
+# Changelog
+All changes are maintained chronologically by date found in the
+[changelog](changelog.yml).
+
+# Copyright
+© Copyright IBM Corporation 2024
+
+# License
+Licensed under [Apache License,
+Version 2.0](https://opensource.org/licenses/Apache-2.0).
+
+# Support
+Please refer to the [support section](../../README.md#support) for
+more details.

zos_basics/unarchive_pax_and_set_custom_facts/ansible.cfg

@@ -0,0 +1,16 @@
+################################################################################
+# Copyright (c) IBM Corporation 2024
+################################################################################
+
+################################################################################
+# Minimum required configuration for this playbook.
+# For additional `ansible.cfg` configuration options, review:
+#   https://docs.ansible.com/ansible/latest/reference_appendices/config.html
+#   https://github.com/ansible/ansible/blob/devel/examples/ansible.cfg
+################################################################################
+
+[defaults]
+forks = 25
+
+[ssh_connection]
+pipelining = True

zos_basics/unarchive_pax_and_set_custom_facts/changelog.yml

@@ -0,0 +1,33 @@
+################################################################################
+# Copyright (c) IBM Corporation 2024
+#
+# All notable changes to this project will be documented in this file. Following
+# releases is a decimal based date since playbooks have no version in this
+# repository.
+#
+# releases:
+#     2020.05.19:
+#         date: 2020-05-19
+#         changes:
+#             added:
+#                 - new features are added
+#             deprecated:
+#                 - features being removed in the future
+#             fixed:
+#                 - bug fixes
+#             minor:
+#                 - changes in existing functionality
+#             removed:
+#                 - features removed no longer available
+#             security:
+#                 - vulnerabilities fixed
+#             summary:
+#                 - summary of changes or link to Git issue, pull request
+################################################################################
+
+releases:
+    2024.09.04:
+        date: 2024-09-04
+        changes:
+            added:
+                - Released initial version

zos_basics/unarchive_pax_and_set_custom_facts/copy_sample_facts_files_to_remote_system.yml

@@ -0,0 +1,49 @@
+  ################################################################################
+# © Copyright IBM Corporation 2024
+################################################################################
+
+################################################################################
+# This playbook copies static files containing sample facts over to the remote
+# target z/OS system using Red Hat Ansible Certified Content for IBM Z.
+# Run this playbook to set up or reset the remote system in preparation for 
+# running the gather_and_print_facts.yml or
+# the unarchive_pax_and_set_custom_facts.yml playbooks.
+#
+# Usage:
+#  ansible-playbook -i <inventory> <playbook>
+#
+# Example:
+#  ansible-playbook -i inventories copy_sample_facts_files_to_remote_system.yml
+#
+# Requirements:
+#   IBM z/OS core collection 1.10.0 or later.
+#
+# Configure:
+#   remote_facts_dir - Path to remote directory which contains static files
+#                      in which local facts are stored as json or ini.
+# 
+################################################################################
+
+---
+- name: Copy local facts stored in static files to remote system.
+  hosts: zos_host
+  collections:
+    - "ibm.ibm_zos_core"
+  environment: '{{ environment_vars }}'
+  gather_facts: false
+
+  vars:
+    remote_facts_dir: /path/to/facts/
+
+  tasks:
+
+  - name: Ensure target directory exists.
+    file:
+      path: "{{ remote_facts_dir }}"
+      state: directory
+
+  - name: Copy local *.fact files to remote z/OS system.
+    zos_copy:
+      src: "{{ playbook_dir }}/files/facts.d/"
+      dest: "{{ remote_facts_dir }}"
+      force: True # to ensure the set up is clean.

zos_basics/unarchive_pax_and_set_custom_facts/files/facts.d/oef.fact

@@ -0,0 +1,6 @@
+{
+    "product_name" : "IBM Open Enterprise Foundation for z/OS",
+    "version" : "1.1",
+    "executable" : "/global/foz/v1r1/bin",
+    "date_last_updated" : "2024-08-28"
+}

zos_basics/unarchive_pax_and_set_custom_facts/files/facts.d/python.fact

@@ -0,0 +1,6 @@
+{
+    "product_name" : "IBM Open Enterprise SDK for Python",
+    "version" : "3.11.3",
+    "executable" : "/allpython/3.11/usr/lpp/IBM/cyp/v3r11/pyz/bin/python3",
+    "date_last_updated" : "2024-08-28"
+}

zos_basics/unarchive_pax_and_set_custom_facts/files/facts.d/zoau.fact

@@ -0,0 +1,8 @@
+{
+    "product_name" : "Z Open Automation Utilities",
+    "zoaversion" : "2024/06/13 14:07:12 CUT v1.3.2.0 edc928b5 5828 PH60438 1232 4da79630",
+    "version" : "1.3.2.0",
+    "executable" : "/zoau/v1.3.2.0",
+    "zoau_pythonpath" : "/zoau/v1.3.2.0/lib/3.11",
+    "date_last_updated" : "2024-08-28"
+}

zos_basics/unarchive_pax_and_set_custom_facts/gather_and_print_facts.yml

@@ -0,0 +1,107 @@
+################################################################################
+# © Copyright IBM Corporation 2024
+################################################################################
+
+################################################################################
+# This playbook demonstrates how to use built in fact gathering to add custom
+# facts from static remote files. An Ansible fact is a variable related to a
+# target system and is accessible throughout playbook execution. Ansible
+# collects certain facts by default and stores them in a variable of type dict
+# called 'ansible_facts'. Custom facts can be added and are nested inside
+# 'ansible_facts' under 'ansible_local'.
+# 
+# This playbook assumes the *.fact files included in the files directory already
+# exist on the remote system. To copy over the included sample files, run the 
+# 'copy_sample_facts_files_to_remote.yml' playbook.
+#
+# Usage:
+#  ansible-playbook -i <inventory> <playbook>
+#
+# Example:
+#  ansible-playbook -i inventories gather_and_print_facts.yml
+#
+# Requirements:
+#   IBM z/OS core collection 1.10.0 or later.
+#
+# Configure:
+#   remote_facts_dir - Path to remote directory which contains static files
+#                      in which local facts are stored as json or ini.
+#
+################################################################################
+
+---
+- name: Gather and print static Ansible facts.
+  hosts: zos_host
+  collections:
+    - "ibm.ibm_zos_core"
+  environment: '{{ environment_vars }}'
+  vars:
+    remote_facts_dir: /path/to/facts/
+
+
+  ##############################################################################
+  # 'gather_facts' and 'fact_path' are play keywords, meaning they are
+  # configurations affecting how a playbook is run.
+  # Ansible, by default, runs many scripts to discover facts about a remote
+  # system. The 'gather_facts' keyword is used to toggle the behavior.
+  # 'gather_facts' is explicitly set to True below to emphasize that fact
+  # gathering is enabled for this playbook. Much of the sample content from Red
+  # Hat Ansible Certified Content for IBM Z has disabled automatic fact
+  # gathering because the facts in question are already known or to achieve a
+  # performance boost by skipping the discovery step.
+  # The default location for storing custom facts on a remote system is
+  # '/etc/ansible/facts.d/'. The 'fact_path' keyword is used to specify a
+  # different directory.
+  ##############################################################################
+  gather_facts: true
+  fact_path: "{{ remote_facts_dir }}"
+
+
+  tasks:
+
+  ##############################################################################
+  # All gathered facts are stored in a dict called 'ansible_facts'.
+  # Custom facts are stored in a dict 'ansible_local', which is nested inside
+  # 'ansible_facts'. Notice however that the 'ansible_local' dict can be
+  # referenced directly and does not require starting at 'ansible_facts', i.e.
+  # 'ansible_facts.ansible_local'.
+  ##############################################################################
+  - name: Print out all the custom facts.
+    ansible.builtin.debug:
+      msg: "{{ ansible_local }}"
+
+  ##############################################################################
+  # Since the facts are stored in a key-value format, they can be accessed and
+  # manipulated conveniently inside of a playbook. The task below builds and
+  # saves a list of all the programs to a variable called 'all_pgms_list' and
+  # the following task prints the list. Unlike the facts from the static files,
+  # facts set in the 'set_fact' module will not persist beyond the playbook run.
+  ##############################################################################
+  - name: Create a list of all programs based on the gathered custom facts.
+    ansible.builtin.set_fact:
+      all_pgms_list: "{{ ansible_local.keys() | list }}"
+
+  - name: Print the list of all programs.
+    debug:
+      var: all_pgms_list
+
+  ##############################################################################
+  # The 'all_pgms_list' can be used to key into the ansible facts dict.
+  # If the data is uniformly structured, a view into the health of the remote
+  # system can be built.
+  # This next task prints the name and date of last update for each program.
+  # This task only prints it, but from here, the data could be fed into an
+  # orchestrator program, for example, one which automatically updates packages.
+  ##############################################################################
+  - name: Print name and date of last update of each program.
+    ansible.builtin.debug:
+      msg: "{{ item }} was last updated: {{ ansible_local[item]['date_last_updated'] }}"
+    loop: "{{ all_pgms_list }}"
+
+  ##############################################################################
+  # Data for individual programs is also acessible.
+  ##############################################################################
+  - name: Print all custom facts for zoau.
+    ansible.builtin.debug:
+      var: ansible_local.zoau
+

zos_basics/unarchive_pax_and_set_custom_facts/inventories/group_vars/all.yml

@@ -0,0 +1,52 @@
+################################################################################
+# Copyright (c) IBM Corporation 2024
+################################################################################
+
+################################################################################
+# Enviroment variables for all z/OS managed nodes (target) that do not need
+# further configuration.
+################################################################################
+environment_vars:
+  _BPXK_AUTOCVT: "ON"
+  ZOAU_HOME: "{{ ZOAU }}"
+  PYTHONPATH: "{{ ZOAU_PYTHON_LIBRARY_PATH }}"
+  LIBPATH: "{{ ZOAU }}/lib:{{ PYZ }}/lib:/lib:/usr/lib:."
+  PATH: "{{ ZOAU }}/bin:{{ PYZ }}/bin:/bin:/var/bin"
+  _CEE_RUNOPTS: "FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)"
+  _TAG_REDIR_ERR: "txt"
+  _TAG_REDIR_IN: "txt"
+  _TAG_REDIR_OUT: "txt"
+  LANG: "C"
+  PYTHONSTDINENCODING: "cp1047"
+
+################################################################################
+# Description of the properties used in this configuration:
+################################################################################
+# - Property BPXK_AUTOCVT must be configured to "ON"; e.g., _BPXK_AUTOCVT: "ON"
+# - Property ZOAU_HOME is the Z Open Automation Utilities (ZOAU) install root path;
+#   e.g., ZOAU_HOME: "/usr/lpp/IBM/zoautil"
+# - Property PYTHONPATH is the Z Open Automation Utilities (ZOAU) Python library path;
+#   e.g., PYTHONPATH: "/usr/lpp/IBM/zoautil/lib"
+# - Property LIBPATH is both the path to the Python libraries on the target
+#   and the Z Open Automation Utilities (ZOAU) Python library path separated by semi-colons; e.g.,
+#   LIBPATH: "/usr/lpp/IBM/zoautil/lib/:/usr/lpp/IBM/cyp/v3r8/pyz/lib:/usr/lib:/lib:."
+# - Property PATH is the ZOA utilities BIN path and Python interpreter path, e.g.,
+#   PATH: "/usr/lpp/IBM/zoautil/bin:/usr/lpp/IBM/cyp/v3r8/pyz/bin:/bin"
+# - Property _CEE_RUNOPTS is the invocation Language Environment® runtime
+#   options for programs and used by Python. e.g.,
+#   _CEE_RUNOPTS: "FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)"
+# - Properties __TAG_REDIR_ERR, _TAG_REDIR_IN, _TAG_REDIR_OUT are txt and used
+#   by the shell; e.g.,
+#      _TAG_REDIR_ERR: "txt"
+#      _TAG_REDIR_IN: "txt"
+#      _TAG_REDIR_OUT: "txt"
+# - Property LANG is the name of the default locale; value
+#   C specifies the POSIX locale; for example: ``LANG: "C"``.
+# - Property `PYTHONSTDINENCODING` should be set to the encoding Unix System Services
+#   is configured as, supported encodings are ASCII or EBCDIC. This environment
+#   variable is used to instruct Ansible which encoding it will *pipe* content to
+#   Python's STDIN (standard in) when `pipelining=true` is set in `ansible.cfg` .
+#   This environment variable will only apply when using IBM Enterprise Python
+#   3.10 or later, otherwise, it is ignored.
+#   For example:`PYTHONSTDINENCODING: "cp1047"`.
+################################################################################