Installing and configuring ZOAU

System requirements

IBM Z Open Automation Utilities has the following requirements.

Software requirements

ZOAU is supported on z/OS 2.4 or later.
Before installing ZOAU, you must be running job entry subsystem 2 (JES2) on your installation. Learn more at z/OS JES2.

Toolkit disk space

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

Optional programs and installed items

To use Python with ZOAU, you must install IBM Open Enterprise SDK for Python version 3.9 or later. Learn more at IBM Open Enterprise SDK for Python.
A samples directory is distributed as part of the ZOAU install. To learn more, see Directory structure.

Installing ZOAU on z/OS

You can install ZOAU via pax or SMP/E.

Install via pax

To download and install ZOAU via pax:

Navigate to Mainframe DEV.
Search for product name "IBM Z Open Automation Utilities" listed under IBM Enterprise DevOps.
Press Download and agree to the Software License Agreement.
Save the zoau-<version>.pax.Z file.
Transfer zoau-<version>.pax.Z to your z/OS host by using binary mode.
Install ZOAU on z/OS by issuing the command:

pax -ppx -rf zoau-<version>.pax.Z

Install via SMP/E

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

Directory structure

The results of the ZOAU 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
samples	C and Python code samples
zoautil_py-stubs	Optional Python stub files

Configuring ZOAU

Complete the following procedure to configure ZOAU.

Set environment variables

Set the following environment variable as shown:
```
export _BPXK_AUTOCVT=ON
```
Create a ZOAU_HOME environment variable that points to the location where ZOAU is installed.
```
export ZOAU_HOME=<PATH_TO_ZOAU>
```
Add ZOAU to the PATH environment variable.
```
export PATH=$PATH:$ZOAU_HOME/bin
```
Add ZOAU to the LIBPATH environment variable.
```
export LIBPATH=$LIBPATH:$ZOAU_HOME/lib
```
(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
```
(Optional) If the user ID that will be running ZOAU commands does not have write access to the high-level qualifier (HLQ) matching its username, use the TMPHLQ environment variable to specify a different HLQ.
```
export TMPHLQ=WRITEHLQ
```

Set APF authorization

Important: Do not use the NOSETUID option when mounting the filesystem on which ZOAU is installed. ZOAU contains APF-authorized programs, and if the NOSETUID option is enabled, then the APF bit will not be honored and ZOAU will not function correctly.

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:

Issue the following command:

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

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.

Set 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.

Protect 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

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. Python 3.12 support requires ZOAU version 1.2.5.1 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.

Filename	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
`zoautil_py-<zoauversion>-cp312-none-any.whl`	3.12

Important: 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.

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 for users of IBM Open Enterprise SDK for Python 3.9: A bug in Python 3.9 causes the ZOAU extension module to be installed with incorrect permissions and file tag. To fix this, apply IBM Open Enterprise SDK for Python 3.9 APAR/PTF PH55814/UI92787. Alternatively, issue the the chmod +x and chtag -b commands for the ZOAU .so files, which are usually located in the active Python /lib directory. These commands add execute permission and properly set the file tag to "binary".
```
chmod +x <Python Library Path>/lib/python3.*/site-packages/zoautil_py/*.abi3.so
chtag -b <Python Library Path>/lib/python3.*/site-packages/zoautil_py/*.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.

If not already done, set the environment variables.
Create a virtual environment by using the following commands:
```
python3 -m venv env
source env/bin/activate
```
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.
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.

Set the following environment variables:

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

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
```

Python stub files

A zoautil_py-stubs directory that contains optional Python stub files is included as part of your ZOAU installation. To import the stub files into your preferred development environment, see your environment's documentation.