Installing and configuring ZOAU

Prerequisites

IBM Z Open Automation Utilities has few prerequisites on z/OS.

Optional programs

Toolkit disk space

ZOAU requires approximately 3000 tracks (200 cylinders) 3390 disk space for product installation.


Installing ZOAU on z/OS

You can install ZOAU via pax or SMP/E.

Installing via pax

To download and install ZOAU via pax:

  1. Navigate to Mainframe DEV.

  2. Search for product name "IBM Z Open Automation Utilities" listed under IBM Enterprise DevOps.

  3. Press Download and agree to the Software License Agreement.

  4. Save the zoau-<version>.pax.Z file.

  5. Transfer zoau-<version>.pax.Z to your z/OS host by using binary mode.

  6. Install ZOAU on z/OS by issuing the command:

    pax -p e -rf zoau-<version>.pax.Z
    

Installing via SMP/E

To install ZOAU on z/OS via SMP/E, see the Program Directory for IBM Z Open Automation Utilities.

The results of the SMP/E installation are a z/OS UNIX directory found at /usr/lpp/IBM/zoautil and a data set containing sample members used for the installation. The zoautil directory contains these subdirectories:

Subdirectory Usage
bin Executable programs
docs Man pages, message catalogs, and other supporting documentation
include Header files
lib API DLL files
LICENSES ZOAU licenses

Configuring ZOAU

Complete the following procedure to configure ZOAU.

Set environment variables

  1. Set the following environment variable as shown:

    export _BPXK_AUTOCVT=ON
    

  2. Create a ZOAU_HOME environment variable that points to the location where ZOAU is installed.

    export ZOAU_HOME=<PATH_TO_ZOAU>
    

  3. Add ZOAU to the PATH environment variable.

    export PATH=$PATH:$ZOAU_HOME/bin
    

  4. Add ZOAU to the LIBPATH environment variable.

    export LIBPATH=$LIBPATH:$ZOAU_HOME/lib
    

  5. (Optional) To use the supplied man pages and view them with the man command, update the MANPATH environment variable.

    export MANPATH=$MANPATH:$ZOAU_HOME/docs/%L
    

Set required authorizations

Check that the APF authorization bit is on for the mvscmdauth and mvscmdauthhelper commands, which should be the case if you install ZOAU by SMP/E. Perform the following steps:

  1. Issue the following command:

    ls -E /usr/lpp/IBM/zoautil/bin/mvscmdauth*
    

  2. Examine the second column of the command output. If it does not show a--- , set it by issuing the following command:

    extattr +a /usr/lpp/IBM/zoautil/bin/mvscmdauth*
    

    If you cannot set the APF authorization bit, you might not have permission to do so. Consult your system programmer.


Install ZOAU Python APIs (optional)

To use the ZOAU Python APIs, use only one of the following installation methods:

  • Python wheel installation method
  • Python setuptools installation method
  • PYTHONPATH environment method

Python wheel installation method

The Python wheel installation method requires ZOAU version 1.2.3 or later.

A wheel file is a ZIP-format archive with a specially formatted file name followed by the .whl extension. It contains a precompiled python module ready to install. Current Python versions support this installation method.

The ZOAU pax archive contains a .whl file for each of the currently supported versions of IBM Open Enterprise SDK for Python. In the following table, <zoauversion> represents the ZOAU version included in the pax archive. For example, the .whl file for IBM Open Enterprise SDK for Python version 3.11 for ZOAU version 1.2.3 has the file name zoautil_py-1.2.3-cp311-none-any.whl.

File Name IBM Open Enterprise SDK for Python version
zoautil_py-<zoauversion>-cp39-none-any.whl 3.9
zoautil_py-<zoauversion>-cp310-none-any.whl 3.10
zoautil_py-<zoauversion>-cp311-none-any.whl 3.11

Warning: The Python wheel installation method performs version matching against the .whl file name. Any modification to the file name can break and corrupt the module installation.

  1. To install the ZOAU API with wheel, run the following command after replacing <zoauversion> with your version of ZOAU (including dots, such as 1.2.3), and <pythonversion> with your version of IBM Open Enterprise SDK for Python (excluding dots, such as 311):

    pip3 install zoautil_py-<zoauversion>-cp<pythonversion>-none-any.whl
    

    Note: Some systems cause the extension module to be installed without proper privileges. To fix this, issue a chmod +x command for the proper .so file, which is usually located in the active python /lib directory.

    chmod +x <Python Library Path>/lib/python3.*/site-packages/zoautil_py/core.abi3.so
    

    Use the type command to find the the active python directory.

    ~$ type python
    python is /u/IBMUSER/venv1/bin/python
    

    In this case, the active Python library path would be /u/IBMUSER/venv1/.


Python setuptools installation method

This method provides pip package manager features and attempts to build Cpython source code for guaranteed PYZ version compatibility.

Note: If you are running IBM Open Enterprise SDK for Python version 3.9 or 3.10 and you want to use the Python setuptools method, you must use the IBM XL C/C++ compiler. If you are running ZOAU version 1.2.2.1 (or later) and IBM Open Enterprise SDK for Python version 3.11 (or later), you can use either the IBM XL C/C++ compiler or the IBM C/C++ for Open Languages Clang compiler.

  1. If not already done, set the environment variables.

  2. Create a virtual environment by using the following commands:

    python3 -m venv env
    source env/bin/activate
    

  3. Find the pip installable package, which is included in the ZOAU pax file. Follow the Installing via pax procedure to download and extract the pax file, from which you can get zoautil_py-<version>.tar.gz.

  4. Install the pip installable package for ZOAU Python APIs with the following command:

    pip3 install zoautil_py-<version>.tar.gz
    

PYTHONPATH environment method

Note: The PYTHONPATH environment method is not recommended for installation. Use the Python wheel installation method.

The PYTHONPATH environment method sets the PYTHONPATH environment variable to point to the zoautil_py directory path containing ZOAU Python APIs and a precompiled binary. The script configure.py checks for and makes the precompiled binary compatible with the present IBM Open Enterprise SDK for Python (PYZ) version on the system.

  1. Set the following environment variables:

    export PYTHONPATH=${PYTHONPATH}:${ZOAU_HOME}/lib
    

  2. Run the configure.py python script to create any required symbolic links to the python shared library. Note that this requires write access to the Python installation directory.

    cd ${ZOAU_HOME}/lib/zoautil_py/config
    python3 configure.py
    

Required authorizations

From ZOAU 1.2.2 forward, the EMCS console created by opercmd has MASTER authority. This authority level enables opercmd users to issue z/OS console commands, and allows opercmd to reply to WTOR messages issued by a different console. Access to opercmd should thus be restricted to authorized users.

From ZOAU v1.2.0.2 forward, specific authorization is required to use jcan and opercmd. An authorized user (such as a system programmer) must define a profile named MVS.MCSOPER.ZOAU and then assign users READ access to that profile.

The following example shows how to use RACF commands to define the MVS.MCSOPER.ZOAU profile and assign users READ access on a system that includes the RACF security product. If your system uses a different security product, consult that product's documentation to configure the required security classes.

RDEFINE OPERCMDS MVS.MCSOPER.ZOAU
PERMIT MVS.MCSOPER.ZOAU CLASS(OPERCMDS) ID(userid) ACCESS(READ)

You might need to modify the previous commands for your installation. To learn more, see Controlling the use of operator commands.


Protecting ZOAU for its APF authorized components

ZOAU includes nine programs installed in the $(ZOAU_HOME)/bin directory that have extended attributes enabled which allow them to behave as if they are loaded from an APF authorized library. ZOAU should be protected with adequate file based permissions to ensure that these utilities are only used by authorized users.

The nine programs are:

  • ddlshelper
  • jcanhelper
  • jlshelper
  • jsubhelper
  • mvscmdauth
  • mvscmdauthhelper
  • opercmdhelper
  • pconhelper
  • pjddhelper

These commands call opercmd directly or indirectly:

  • apfadm
  • llwhence
  • parmgrep
  • pparm
  • parmwhence (calls opercmd indirectly through pparm)
  • pproc
  • procgrep (calls opercmd indirectly through pproc)
  • procwhence (calls opercmd indirectly through pproc)

The mvscmdauth utility can be used to invoke APF authorized programs as part of a ZOAU script. Other utilities also use these programs:

  • dcp
  • ddiff
  • dgrep
  • dlsraw
  • dmv
  • drm
  • dunzip
  • dzip
  • mmv
  • mrm
  • parmgrep
  • procgrep