Merge branch 'main' into ibm_concert

IBM · Oct 29, 2024 · 10cc147 · 10cc147
2 parents 9a76860 + 88a0f72
commit 10cc147
Show file tree

Hide file tree

Showing 80 changed files with 2,457 additions and 512 deletions.
diff --git a/README.md b/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
@@ -141,7 +142,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

diff --git a/docs/share/zos_core/configuration_guide.md b/docs/share/zos_core/configuration_guide.md
@@ -121,13 +121,15 @@ execution.
 `group_vars` environment variables:
 
 - Property `BPXK_AUTOCVT` must be configured to `"ON"`; e.g., `_BPXK_AUTOCVT: "ON"`
-- Property `ZOAU_HOME` is the **ZOA Utilities** install root path; e.g., `ZOAU_HOME: "/usr/lpp/IBM/zoautil"`
-- Property `PYTHONPATH` is the **ZOA Utilities** Python library path; e.g., `PYTHONPATH: "/usr/lpp/IBM/zoautil/lib"`
+- 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/zoau-wheel/"`
 - Property `LIBPATH` is **both** the path to the **Python libraries** on the target
-  and the **ZOA Utilities 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:."`
+  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/v3r12/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"`
+  `PATH: "/usr/lpp/IBM/zoautil/bin:/usr/lpp/IBM/cyp/v3r12/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)"`
@@ -154,7 +156,7 @@ A complete example of `all.yml` is:
 environment_vars:
   _BPXK_AUTOCVT: "ON"
   ZOAU_HOME: "{{ ZOAU }}"
-  PYTHONPATH: "{{ ZOAU }}/lib"
+  PYTHONPATH: "{{ ZOAU_PYTHON_LIBRARY_PATH }}"
   LIBPATH: "{{ ZOAU }}/lib:{{ PYZ }}/lib:/lib:/usr/lib:."
   PATH: "{{ ZOAU }}/bin:{{ PYZ }}/bin:/bin:/var/bin:/usr/sbin"
   _CEE_RUNOPTS: "FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)"
@@ -183,7 +185,7 @@ complete the configuration.
 `host_vars` environment variables:
 
 - Property `PYZ` is the python installation home path on the z/OS managed node
-  (target), e.g, `pyz: "/usr/lpp/IBM/cyp/v3r8/pyz"`
+  (target), e.g, `pyz: "/usr/lpp/IBM/cyp/v3r12/pyz"`
 - Property `ZOAU` is the ZOAU installation home on the z/OS managed node
   (target), e.g, `zoau: "/usr/lpp/IBM/zoautil"`
 - Property `ansible_python_interpreter` is the z/OS managed node (target) Python
@@ -194,8 +196,10 @@ complete the configuration.
 A complete example of `zos_host.yml` is:
 
 ``` {.yaml}
-PYZ: "/usr/lpp/IBM/cyp/v3r8/pyz"
+PYZ: "/usr/lpp/IBM/cyp/v3r12/pyz"
 ZOAU: "/usr/lpp/IBM/zoautil"
+ZOAU_PYTHON_LIBRARY_PATH: "{{ path_to_wheel_installation_directory }}"
+
 ansible_python_interpreter: "{{ PYZ }}/bin/python3"
 ```
 

diff --git a/docs/share/zos_core/configure_host_vars.md b/docs/share/zos_core/configure_host_vars.md
@@ -6,7 +6,7 @@ established.
 
 ## Description of the environment variables used in this configuration
 * Environment variable `PYZ` is the Python home installation path on the
-  z/OS managed node (target), e.g, `pyz: "/usr/lpp/IBM/cyp/v3r8/pyz"`
+  z/OS managed node (target), e.g, `pyz: "/usr/lpp/IBM/cyp/v3r12/pyz"`
 * Environment variable `ZOAU` is the ZOAU installation home on the z/OS managed
   node (target), e.g, `zoau: "/usr/lpp/IBM/zoautil"`
 * Environment variable `ansible_python_interpreter` is the Python binary
@@ -18,8 +18,10 @@ Configure `PYZ` and `ZOAU` in the included **group_vars** configuration.
 For example:
 
 ```yaml
-PYZ: "/u/oeusr01/python/pyz_3_8_2/usr/lpp/IBM/cyp/v3r8/pyz"
+PYZ: "/usr/lpp/IBM/cyp/v3r12/pyz"
 ZOAU: "/usr/lpp/IBM/zoautil"
+ZOAU_PYTHON_LIBRARY_PATH: "{{ path_to_wheel_installation_directory }}"
+
 ansible_python_interpreter: "{{ PYZ }}/bin/python3"
 ```
 

diff --git a/docs/share/zos_core/configure_inventory.md b/docs/share/zos_core/configure_inventory.md
@@ -4,8 +4,8 @@ will connect. Also part of the inventory is the user that Ansible should
 connect to over SSH to the managed host.
 
 ## Description of the properties used in this configuration
-* Property `ansible_host` is the z/OS managed node (target), e.g, `ansible_host: "zvm1.vmec.svl.ibm.com"`
-* Property `ansible_user` is the z/OS managed user to connect and run as over SSH,  e.g, `ansible_user: "zosadm"`
+* Property `ansible_host` is the z/OS managed node (target), e.g, `ansible_host: "zos-system.ibm.com"`
+* Property `ansible_user` is the z/OS managed user to connect and run as over SSH,  e.g, `ansible_user: "zosusr"`
 
 Configure `ansible_host` and `ansible_user` in the included inventory.
 
@@ -15,8 +15,8 @@ For example:
 source_system:
   hosts:
     zos_host:
-      ansible_host: "zvm1.vmec.svl.ibm.com"
-      ansible_user: "zosadm"
+      ansible_host: "zos-system.ibm.com"
+      ansible_user: "zosusr"
 ```
 
 If you are unfamiliar with playbook configuration practices and would like to

diff --git a/zos_basics/constructs/inventories/group_vars/all.yml b/zos_basics/constructs/inventories/group_vars/all.yml
@@ -1,5 +1,5 @@
 ################################################################################
-# Copyright (c) IBM Corporation 2020
+# Copyright (c) IBM Corporation 2020, 2024
 ################################################################################
 
 ################################################################################
@@ -9,7 +9,7 @@
 environment_vars:
   _BPXK_AUTOCVT: "ON"
   ZOAU_HOME: "{{ ZOAU }}"
-  PYTHONPATH: "{{ ZOAU }}/lib"
+  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)"
@@ -23,10 +23,12 @@ environment_vars:
 # 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 ZOA Utilities install root path; e.g., ZOAU_HOME: "/usr/lpp/IBM/zoautil"
-# - Property PYTHONPATH is the ZOA Utilities Python library path; e.g., PYTHONPATH: "/usr/lpp/IBM/zoautil/lib"
+# - 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 ZOA Utilities Python library path separated by semi-colons; e.g.,
+#   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"

diff --git a/zos_basics/constructs/inventories/host_vars/zos_host.yml b/zos_basics/constructs/inventories/host_vars/zos_host.yml
@@ -1,25 +1,64 @@
 ---
 ################################################################################
-# Copyright (c) IBM Corporation 2021
+# Copyright (c) IBM Corporation 2021, 2024
 ################################################################################
 
 ################################################################################
 # Description of the properties used in this configuration:
-# - Property `PYZ` is the python installation home path on the z/OS managed node (target),
-#    e.g, pyz: "/usr/lpp/IBM/cyp/v3r8/pyz"
-# - Property `ZOAU` is the ZOAU installation home on the z/OS managed node (target),
-#    e.g, zoau: "/usr/lpp/IBM/zoautil"
-# - property `ansible_python_interpreter` is the z/OS managed node (target) Python
+# - Property `PYZ` is the python installation home path on the z/OS managed
+#    (target) node e.g, PYZ: "/usr/lpp/IBM/cyp/v3r12/pyz"
+# - Property `PYZ_VERSION` is the version of python on the z/OS managed
+#    (target) node e.g, PYZ_VERSION: "3.12".
+# - Property `ZOAU` is the ZOAU installation home on the z/OS managed (target)
+#    node, e.g, ZOAU: "/usr/lpp/IBM/zoautil".
+# - Property `ZOAU_PYTHON_LIBRARY_PATH` is the path to the Z Open Automation
+#    Utilities (ZOAU) python library. Specifically, the path points to the
+#    directory containing 'zoautil_py'. Packages installed using 'pip' generally
+#    default to the 'site-packages' directory within the python installation,
+#    eg "/usr/lpp/IBM/cyp/v3r12/pyz/lib/python3.12/site-packages/".
+#    If the installation uses options such as '--user' or '--target', the module
+#    is installed to a non-default location which must be configured in
+#    `ZOAU_PYTHON_LIBRARY_PATH`.
+#    If the wheel installation method is used with the '--target' or '--user'
+#    option, `ZOAU_PYTHON_LIBRARY_PATH` should point to the directory the wheel
+#    file was installed to. e.g ZOAU_PYTHON_LIBRARY_PATH: "/usr/zoau-wheel/".
+#    Else 'ZOAU_PYTHON_LIBRARY_PATH' should point to the directory containing
+#    the pre-compiled binary.
+#    For ZOAU v1.2.x, the pre-compiled binary is located in the 'lib' directory.
+#    e.g "/usr/lpp/IBM/zoautil/lib" or "{{ ZOAU }}/lib".
+#    For ZOAU v1.3.x, the pre-compiled binary is located in a sub-directory
+#    corresponding to the `PYZ_VERSION` inside the 'lib' directory,
+#    e.g "/usr/lpp/IBM/zoautil/lib/3.12" or "{{ ZOAU }}/lib/{{ PYZ_VERSION }}".
+# - Property `ansible_python_interpreter` is the z/OS managed node (target) Python
 #    binary installation path, e.g, ansible_python_interpreter: "{{PYZ}}/bin/python3"
 #
-# Note, PYZ and ZOAU environment variables must be configured.
+# Note, PYZ, PYZ_VERSION, and ZOAU environment variables must be configured.
 ################################################################################
 
 PYZ: "path_to_python_installation_on_zos_target"
+PYZ_VERSION: "3.xx"
+
 ZOAU: "path_to_zoau_installation_on_zos_target"
 
+# Configuring the `ZOAU_PYTHON_LIBRARY_PATH` property is required.
+
+# If the ZOAU python package, zoautil_py, has been installed as a wheel (*.whl)
+# with the '--target' or '--user' option, uncomment the following line:
+# ZOAU_PYTHON_LIBRARY_PATH: "{{ path_to_wheel_installation_directory }}"
+
+# If the ZOAU python zoautil_py package has been installed in the default location
+# that is part of Python's search path, the `ZOAU_PYTHON_LIBRARY_PATH` environment
+# variable must be set as an empty string. Uncomment the following line:
+# ZOAU_PYTHON_LIBRARY_PATH: ""
+
+# If using pre-compiled binaries for ZOAU v1.3.x, uncomment the following line:
+# ZOAU_PYTHON_LIBRARY_PATH: "{{ ZOAU }}/lib/{{ PYZ_VERSION }}"
+
+# If using pre-compiled binaries for ZOAU v1.2.x, uncomment the following line:
+# ZOAU_PYTHON_LIBRARY_PATH: "{{ ZOAU }}/lib"
+
 ################################################################################
-# Do not configure, variable substituion will correctly set the
-# variable`ansible_python_interpreter`
+# Do not configure, variable substitution will correctly set the
+# variable `ansible_python_interpreter`
 ################################################################################
 ansible_python_interpreter: "{{ PYZ }}/bin/python3"
diff --git a/zos_basics/factgathering/inventories/group_vars/all.yml b/zos_basics/factgathering/inventories/group_vars/all.yml
@@ -1,5 +1,5 @@
 ################################################################################
-# Copyright (c) IBM Corporation 2023
+# Copyright (c) IBM Corporation 2023, 2024
 ################################################################################
 
 ################################################################################
@@ -10,7 +10,7 @@
 environment_vars:
   _BPXK_AUTOCVT: "ON"
   ZOAU_HOME: "{{ ZOAU }}"
-  PYTHONPATH: "{{ ZOAU }}/lib"
+  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)"
@@ -24,10 +24,12 @@ environment_vars:
 # 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 ZOA Utilities install root path; e.g., ZOAU_HOME: "/usr/lpp/IBM/zoautil"
-# - Property PYTHONPATH is the ZOA Utilities Python library path; e.g., PYTHONPATH: "/usr/lpp/IBM/zoautil/lib"
+# - 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 ZOA Utilities Python library path separated by semi-colons; e.g.,
+#   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"

diff --git a/zos_basics/factgathering/inventories/host_vars/zos_host.yml b/zos_basics/factgathering/inventories/host_vars/zos_host.yml
@@ -1,25 +1,64 @@
 ---
 ################################################################################
-# Copyright (c) IBM Corporation 2023
+# Copyright (c) IBM Corporation 2023, 2024
 ################################################################################
 
 ################################################################################
 # Description of the properties used in this configuration:
-# - Property `PYZ` is the python installation home path on the z/OS managed node (target),
-#    e.g, pyz: "/usr/lpp/IBM/cyp/v3r8/pyz"
-# - Property `ZOAU` is the ZOAU installation home on the z/OS managed node (target),
-#    e.g, zoau: "/usr/lpp/IBM/zoautil"
-# - property `ansible_python_interpreter` is the z/OS managed node (target) Python
+# - Property `PYZ` is the python installation home path on the z/OS managed
+#    (target) node e.g, PYZ: "/usr/lpp/IBM/cyp/v3r12/pyz"
+# - Property `PYZ_VERSION` is the version of python on the z/OS managed
+#    (target) node e.g, PYZ_VERSION: "3.12".
+# - Property `ZOAU` is the ZOAU installation home on the z/OS managed (target)
+#    node, e.g, ZOAU: "/usr/lpp/IBM/zoautil".
+# - Property `ZOAU_PYTHON_LIBRARY_PATH` is the path to the Z Open Automation
+#    Utilities (ZOAU) python library. Specifically, the path points to the
+#    directory containing 'zoautil_py'. Packages installed using 'pip' generally
+#    default to the 'site-packages' directory within the python installation,
+#    eg "/usr/lpp/IBM/cyp/v3r12/pyz/lib/python3.12/site-packages/".
+#    If the installation uses options such as '--user' or '--target', the module
+#    is installed to a non-default location which must be configured in
+#    `ZOAU_PYTHON_LIBRARY_PATH`.
+#    If the wheel installation method is used with the '--target' or '--user'
+#    option, `ZOAU_PYTHON_LIBRARY_PATH` should point to the directory the wheel
+#    file was installed to. e.g ZOAU_PYTHON_LIBRARY_PATH: "/usr/zoau-wheel/".
+#    Else 'ZOAU_PYTHON_LIBRARY_PATH' should point to the directory containing
+#    the pre-compiled binary.
+#    For ZOAU v1.2.x, the pre-compiled binary is located in the 'lib' directory.
+#    e.g "/usr/lpp/IBM/zoautil/lib" or "{{ ZOAU }}/lib".
+#    For ZOAU v1.3.x, the pre-compiled binary is located in a sub-directory
+#    corresponding to the `PYZ_VERSION` inside the 'lib' directory,
+#    e.g "/usr/lpp/IBM/zoautil/lib/3.12" or "{{ ZOAU }}/lib/{{ PYZ_VERSION }}".
+# - Property `ansible_python_interpreter` is the z/OS managed node (target) Python
 #    binary installation path, e.g, ansible_python_interpreter: "{{PYZ}}/bin/python3"
 #
-# Note, PYZ and ZOAU environment variables must be configured.
+# Note, PYZ, PYZ_VERSION, and ZOAU environment variables must be configured.
 ################################################################################
 
-# PYZ: "path_to_python_installation_on_zos_target"
-# ZOAU: "path_to_zoau_installation_on_zos_target"
+PYZ: "path_to_python_installation_on_zos_target"
+PYZ_VERSION: "3.xx"
+
+ZOAU: "path_to_zoau_installation_on_zos_target"
+
+# Configuring the `ZOAU_PYTHON_LIBRARY_PATH` property is required.
+
+# If the ZOAU python package, zoautil_py, has been installed as a wheel (*.whl)
+# with the '--target' or '--user' option, uncomment the following line:
+# ZOAU_PYTHON_LIBRARY_PATH: "{{ path_to_wheel_installation_directory }}"
+
+# If the ZOAU python zoautil_py package has been installed in the default location
+# that is part of Python's search path, the `ZOAU_PYTHON_LIBRARY_PATH` environment
+# variable must be set as an empty string. Uncomment the following line:
+# ZOAU_PYTHON_LIBRARY_PATH: ""
+
+# If using pre-compiled binaries for ZOAU v1.3.x, uncomment the following line:
+# ZOAU_PYTHON_LIBRARY_PATH: "{{ ZOAU }}/lib/{{ PYZ_VERSION }}"
+
+# If using pre-compiled binaries for ZOAU v1.2.x, uncomment the following line:
+# ZOAU_PYTHON_LIBRARY_PATH: "{{ ZOAU }}/lib"
 
 ################################################################################
-# Do not configure, variable substituion will correctly set the
-# variable`ansible_python_interpreter`
+# Do not configure, variable substitution will correctly set the
+# variable `ansible_python_interpreter`
 ################################################################################
 ansible_python_interpreter: "{{ PYZ }}/bin/python3"