Installing and configuring ZOAU

Software requirements

ZOAU is supported on z/OS v2.5 or later.

ZOAU requires one of the following job entry systems on your installation:

• JES2 (job entry subsystem 2). Learn more at z/OS JES2.
• JES3 (job entry subsystem 3). Learn more at z/OS JES3.

Required disk space

ZOAU requires approximately 750 tracks (50 cylinders), or 35MB of 3390 disk space for product installation.

To operate correctly, ZOAU requires a writable temporary directory (typically /tmp) with at least 100 MB of free space.

Installed items and optional programs

To use the ZOAU Python language pack, you must install IBM Open Enterprise SDK for Python version 3.12 or later. Learn more at IBM Open Enterprise SDK for Python.

The results of the ZOAU installation are a z/OS UNIX directory found at /usr/lpp/IBM/zoau/v1r4. The following subdirectories are included in the distribution:

Installing with pax

To download and install ZOAU with pax:

1. Navigate to Mainframe Downloads.

2. Search for the 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 to your local device.

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

6. Log in to your z/OS system. Ensure that the current user ID has the ability to set the APF authorization bit on a file; this can be the superuser or a user who has READ access to the BPX.FILEATTR.APF resource in the FACILITY class. To learn more, see Controlling who can set the APF-authorized attribute.

7. Continuing on z/OS, create and mount a new zFS filesystem as read-write.

8. Use the cd command to change the working directory to the new zFS filesystem.

9. Use the pax command to install ZOAU into the new zFS filesystem:

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

   
   

   If the command produces an error message, the current user ID does not have sufficient authority to install ZOAU. For example, you might see the following error:

   pax: FSUMF073 bin/opercmdhelper: user not authorized to restore extended attribute "a"
   

   
   

   To remedy this situation, review the previous steps or consult your system programmer.

10. Change to the prior directory (cd -). The ZOAU filesystem cannot be remounted while it is in use.

11. Remount the ZOAU filesystem as read-only. The typical installation location for ZOAU is /usr/lpp/IBM/zoau/v1r4. You can do this with the chmount command:

    /usr/sbin/chmount -r <ZOAU_INSTALL_DIR>
    

12. Ensure that ZOAU is installed on a read-only mount path. This avoids creation of unnecessary .pyc files when the ZOAU Python language pack is used. The .pyc files can cause issues in shared environments and complicate software maintenance. Mounting the ZOAU as read-only ensures a clean and consistent installation across systems.

Install with SMP/E

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

Temporary directory

To function properly, ZOAU requires a writable temporary directory with a minimum of 100 MB of free space. Typically mounted at /tmp, the temporary directory on z/OS should be a standalone zFS or TFS filesystem.

Unexpected behavior can occur if the temporary directory is full and ZOAU cannot write to it. Ensure it is large enough not to completely fill during typical system workloads. To monitor the amount of free space available, use the following methods:

• Monitoring space in the TFS
• The AGGRFULL option in the zFS MOUNT command

Set environment variables

An environment variable pairs a case-sensitive variable name with an assigned value in the form VARNAME=VALUE. Use environment variables with ZOAU to define and provide specific characteristics of your environment to the UNIX System Services and utilities at runtime.

Several environment variables must be set correctly for ZOAU to function properly. Some are unique to ZOAU, others are general to UNIX System Services. To learn more about general settings, see Abstract for z/OS UNIX System Services Planning.

Perform the following steps to configure required and optional environment variables for ZOAU.

_BPXK_AUTOCVT enables automatic conversion of tagged files. When set, this variable overrides the AUTOCVT setting in BPXPRMxx. The default setting is OFF. To ensure that ASCII-tagged content is properly handled by z/OS, set the _BPXK_AUTOCVT variable to ON:

export _BPXK_AUTOCVT=ON

To learn more about _BPXK_AUTOCVT, see _BPXK environment variables.

Create a ZOAU_HOME environment variable that points to the directory where ZOAU is installed. The default location is /usr/lpp/IBM/zoau/v1r4.

export ZOAU_HOME=<PATH_TO_ZOAU>

PATH sets a default command search path to search the directories concatenated in this string. Add ZOAU to the PATH environment variable.

export PATH=${PATH}:${ZOAU_HOME}/bin

LIBPATH specifies the directory to search for a dynamic link library (DLL). Add ZOAU to the LIBPATH environment variable.

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

To learn more about PATH, LIBPATH, and MANPATH, see Customizing /etc/profile.

(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) TMPHLQ is a ZOAU-specific environment variable that is used by the mvstmp utility. If the user ID that runs 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>

(Optional) By default, temporary files are written to the /tmp directory. Use the TMPDIR standard environment variable to write temporary files to an alternate directory.

export TMPDIR=/tmp

(Optional) CONSBUFPGNUM is a ZOAU-specific environment variable and is used by opercmd. Use CONSBUFPGNUM to specify the number of buffer pages allocated to command output.

export CONSBUFPGNUM=128

(Optional) CONCHAR sets the JES command prefix character to be used in the cancel command. The default prefix character for JES2 is '$', and for JES3 it is '*'. Set this if your installation uses a non-default command prefix character, or if you have multiple JES instances running simultaneously.

For more information about JES command prefix characters, see the z/OS documentation.

(Optional) To validate the ZOAU installation, run the following command, which reports any problems with the installation or configuration. This creates a report that can be used when you are working with IBM Support.

zoaversion -c

Set APF authorization

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

If you install ZOAU with SMP/E, the APF authorization bits should be correctly set for you, and this step should not be necessary. Otherwise, you can check that the APF authorization bit is on for the required commands.

1. Issue the following command:

   zoaversion -c
   

   
   

2. A ZOAU diagnostic report is printed to the terminal. If any files are listed as missing the APF bit, the following error message is displayed.

   Error: <FILENAME> does not have the APF authorization bit set.
   

   
   

   You can set the APF bit on the file with the following command:

   extattr +a ${ZOAU_HOME}/bin/<FILENAME>
   

   
   

   If you receive an error message when issuing the extattr command, then your user ID may not have the authority to set the APF bit. You must use either the superuser ID or a user who has READ access to the BPX.FILEATTR.APF resource in the FACILITY class. Contact your system programmer for more information.

Setting console command authority

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.

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)
SETROPTS RACLIST(OPERCMDS) REFRESH

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

Using UNIX group permissions to restrict access to ZOAU

To restrict access to ZOAU's APF-authorized components, you can use UNIX group permissions. Create a dedicated group (for example, zoaugrp) and assign authorized users to this group. Then, change the ownership and permissions of the ZOAU installation directory to restrict access.

This configuration allows only the owner and members of the zoaugrp group to run ZOAU commands. Manage the group membership through your security product to maintain the desired access control.

chgrp -R zoaugrp ${ZOAU_HOME}
chmod -R 750 ${ZOAU_HOME}/bin

Minimum Python versions

ZOAU is compatible with the following minimum versions of IBM Open Enterprise SDK for Python. To learn more, see IBM Open Enterprise SDK for Python Installation and Configuration.

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

• Python wheel installation
• PYTHONPATH environment variable
• Python setuptools installation (not recommended)

Python wheel installation method

A wheel file is a ZIP-format archive with a specially formatted filename followed by the .whl extension. It contains a precompiled Python module ready to install.

The ZOAU installation directory 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 installed ZOAU version.

For example, the .whl file for IBM Open Enterprise SDK for Python version 3.14 for ZOAU version 1.4.1.0 has the filename zoautil_py-1.4.1.0-cp314-cp314-zos.whl.

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

To install the ZOAU Python module with a wheel package, run the following command after replacing <wheel_filename> with the corresponding wheel filename that matches your version of IBM Open Enterprise SDK for Python.

pip3 install <wheel_filename>

For example, the command to install the Python 3.14 version of the ZOAU 1.4.1.0 wheel package is:

pip3 install zoautil_py-1.4.1.0-cp314-cp314-zos.whl

PYTHONPATH environment variable method

The PYTHONPATH environment variable method sets this to point to the zoautil_py directory path containing the ZOAU Python APIs and a precompiled binary.

This environment variable must be set to the correct ZOAU directory that corresponds to the version of Python installed on your z/OS system.

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

2. Run the command python3 --version to determine the version of Python on your systems. The version number used in this case is the first two digits in the output. For example:

   ~> python3 --version
   Python 3.14.0
   # The python version is 3.14.
   

3. Set the PYTHONPATH environment variable. The final part of the path corresponds to the version number of the Python runtime. Ensure that you adjust the value to match what is installed on your system. Note that this step requires the ZOAU_HOME environment variable to be set.

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

Python setuptools installation method (not recommended)

Note: The Python setuptools method is not recommended due to additional complexity and software requirements. Only use this method if neither of the others work for you.

This installation method requires one of the following C compilers to build the CPython source code in the ZOAU language pack.

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

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, consult the documentation.