Installing the z/OS Java Agent

Important! These installation instructions apply only to the installation of the Java-based z/OS Agent that replaces the old one.

This page guides you through the installation of a z/OS Agent in an Automation Engine system in which authentication is not used. Additional installation steps are required before the agent can be started and used if you intend to use one of the available authentication methods. For more information, see Agent Authentication.

Check the compatibility matrix to see which version is compatible with your system. For more information, see Compatibility Information.

This Agent supports sending emails using SMTP and SMTPS. For more information, see Setting Up Email Connections.

This page includes the following:

Requirements

The following sections describe some important topics that you must consider when installing and configuring the Agent.

Java Runtime Environment (JRE)

The Agent requires a JRE (version 17 or higher). You can make it available either through a system-wide Java installation or through a minimal JRE version.

When started, the Agent's launcher application looks for the JRE using on of the following methods:
1. Using the JAVA_HOME environment variable.
2. Executing the java -XshowSettings:properties command to find a working Java installation. The launcher uses the PATH environment variable to locate the executable. If the command succeeds (which means that the JVM starts), the path of the running JVM is retrieved from the command's output.
The launcher then starts the JRE and loads the Agent's jar file.
JES2 or JES3
TCP/IP V3R2M0 or later
APF authorization for the load library
APF authorization for the ucxjase executable
Program Controlled attribute for libZOSNative.so .
C runtime library version V1R5M0 or later
An MSGCLASS in HOLD status that does not call a subsequent program (external writer)
UPDATE access for JESSPOOL RACF Class (to process Job outputs)
A file qualifier for temporary files, logs, and traces

Preparing the OMVS Environment

Follow these steps to prepare your OMVS environment for the Agent:

Convert character encoding.

z/OS uses EBCDIC encoding, so converting between ASCII and EBCDIC is necessary. CCSID identifies the data representation.
Enable automatic conversion.

Use the following command to enable automatic conversion:

export _BPXK_AUTOCVT=ON
Set the CCSID attribute.

After transferring files, set the correct CCSID attribute:

chtag -t -c 819 file_path
List file attributes.

Use ls -T to list file attributes.
Set the OMVS environment.

Set up your OMVS environment with a script. Here is a sample script:

export TERM=xterm

export _BPXK_AUTOCVT=ON

export JAVA_HOME=/C/java/java64bt/v11r0m0/usr/lpp/java/current_64/ export PATH=$PATH:/C/java/java64bt/v11r0m0/usr/lpp/java/current_64/bin bash

Connecting to the Automation Engine

The Automation Engine and the Windows, UNIX, and Java Agents communicate using TLS/SSL. These agents establish a connection with the Java communication process (JCP), which uses trusted certificates to prove their identity to other communication partners.

Important! Make sure you are familiar with the TLS/SSL and certificate implementation before installing and/or upgrading the respective component. For more information, see:

When you used certificates signed by a CA, the certificates are stored in the respective Java or OS store by default; that is the Java trust store for Java components and Java Agents, the Windows OS store for Windows Agents, or the TLS/SSL store for UNIX Agents. In this case, you only have to check that the root certificates already are in the respective store.

If the relevant certificates are not there and you want to import them, you can use OS or Java specific tools for that purpose, such as Keytool, cert-manager, OpenSSL and such. For more information on how to use those tools, please refer to the respective product documentation.

If you do not want to use the default locations for the components and Agents listed above, make sure you use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters (if applicable) in the respective configuration (INI) file to define the path to the folder where the trusted certificates are stored.

Important! TLS/SSL Agents (in containers and on-premises) as well as the TLS Gateway, when used for the Automic Automation Kubernetes Edition, establish a connection to an ingress / HTTPS load balancer, which requires a certificate for authentication.

Make sure that address of the load balancer is defined on both sides: the Automation Engine and the Agent / TLS Gateway and that your HTTPS load balancer has the required certificates in place. For more information, see Connecting to AWI, the JCP and REST Processes Using an Ingress.

Installing the Java Agent for z/OS

Transfer the necessary files from IMAGE:AGENTS\MVS\ to the host. Use an FTP user with appropriate rights:
- User name: UC4
- Password: <as defined>
UNIX Example:

ascii

quote site lrecl=500 blksize=27500

put UCXEM25.ini 'UC4.UCXEM25.INI'

quote site recfm=vb lrecl=500 blksize=27998

put ucx.msl 'UC4.UC.MSL'

quit

Note: The ucx.msl and INI files are delivered with LF EOL format (UNIX/Linux encoding). However, some FTP Clients on Windows require the CRLF EOL format. To make sure you use the correct EOL format for Windows you could, for example, use a file editor to change LF to CRLF or use the appropriate function of your FTP client.
Upload Automation.Engine_Agent_MVS_rezipped.zip to the installation root of the zOS Agent in USS.
Extract the Agent installation package (a .zip file) to any host.
Install all files into a USS folder and adapt the INI file.
Install the MVS objects.

The ucxj25m-ibm.bin file available in the ./bin folder contains MVS load modules that you must copy into a dataset. Use TSO.

Use the following command:

cp -P LRECL=80,RECFM=FB,BLKSIZE=3120 ucxjm25-ibm.bin "//'UC4.#BIN'"

With the following job, you can extract the contents of TSO transmit dataset into a load library:

//UC4LOAD JOB (ACCT#),'UC4USER',

// CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)

//RECV EXEC PGM=IKJEFT01,DYNAMNBR=30

//SYSPRINT DD SYSOUT=*

//SYSTSPRT DD SYSOUT=*

//SYSTSIN DD *

PROFILE NOPREFIX

RECEIVE USERID(UC4USER)INDSN ('UC4.#BIN')

DSNAME ('UC4.LOADLIB')

/*
The Agent runs on the host as a started task. The supplied files include a JCL example. Copy this JCL to a system procedure library.

Note: Make sure to set the Agent installation USS path and JAVA_HOME environment variable.

Example of a started task

//UC4RUN PROC

//AGENT EXEC PGM=JVMLDM17,REGION=0M,

// PARM='/+I com.automic.agent.UCXJOSS'

//SYSPRINT DD SYSOUT=* < SYSTEM STDOUT

//SYSOUT DD SYSOUT=* < SYSTEM STDERR

//STDOUT DD SYSOUT=* < JAVA SYSTEM.OUT

//STDERR DD SYSOUT=* < JAVA SYSTEM.ERR

//CEEDUMP DD SYSOUT=*

//ABNLIGNR DD DUMMY

//STDENV DD *

export APP_HOME=<agent installation USS path>

export JAVA_HOME=<java17 home>

# set up PATH

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

# set up LIBPATH

export LIBPATH=${LIBPATH}:${JAVA_HOME}/bin

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

export LIBPATH=${LIBPATH}:${JAVA_HOME}/lib/j9vm

export LIBPATH=${LIBPATH}:${JAVA_HOME}/lib/default

export LIBPATH=${LIBPATH}:${APP_HOME}

# setup CLASSPATH

export CLASSPATH=${APP_HOME}/ucxjoss.jar

export CLASSPATH=${APP_HOME}:${CLASSPATH}

export CLASSPATH=${JAVA_HOME}/lib:${CLASSPATH}

# make sure JZOS batch loader sets PWD to APP_HOME

export PWD=${APP_HOME}

# set up java options and rest environment variables

export JD1="-Djdk.internal.httpclient.disableHostnameVerification=true"

export JD2="-Dfile.encoding=UTF-8"

export IBM_JAVA_OPTIONS="${JD1} ${JD2}"

export _BPXK_AUTOCVT=OFF

/*
Ensure that libZOSNative.so has executable flags set and program control authorized.

extattr +p libZOSNative.so
Ensure that ucxjase has executable flags set and program control and APF authorized.

extattr +ap ucxjase
Ensure you have APF authorization for the load library. Add it dynamically to the system console using the following command on the host:

SETPROG APF,ADD,DSN=UC4.LOADLIB, [SMS] [VOLUME=xxx]
Ensure that the following authorizations are set:
1. User, groups and data set profiles.
  
  The user under which the Agent runs requires the relevant rights for data sets via the user or group definition. You can use the data set profiles to assign the respective rights. The AE data set qualifier requires alter rights.
  
  Note: The Agent requires rights for all data sets to be used.
2. OMVS Segment (TCP/IP authorization).
  
  Make sure that the OMVS rights are specified in the user and default group.
3. General resource.
  
  Usually, there is a general resource for started tasks (STC). You can assign general rights here to enable the agent program to run as a STC. You can also define the user to be used to run the agent (STDATA).
4. Required and recommended RACF settings.
  
  Required
  
  The following RACF settings are required if the USS file system is used:
  - FACILITY class BPX.DAEMON profile with UACC(READ)
  - PROGRAM class * profile, MEMBER(loadlib//NOPADCHK)
    
    Note: This authorization is required for the Event Monitor.
  Recommended
  
  The following RACF settings are recommended to use the ft_thread_level_security=yes (default) parameter of the INI file of the z/OS agent (see Agent z/OS).
  
  The Agent user needs:
  - OMVS segment
  - FACILITY BPX.DAEMON FACILITY class resource with Read access
  - FACILITY BPX.SERVER FACILITY class resource with Read access
  - FACILITY BPX.WLMSERVER FACILITY class resource with Read access
  - SUPERUSER.FILESYS.CHOWN UNIXPRIV class resource with Read access
  - BPX.SRV.loginUid SURROGAT class resource with Read access for all logins
  The login user needs:
  - OMVS segment
  - OMVSAPPL APPL class resource with Read access
  - BPX.SRV.loginUid SURROGAT class resource where the agent user has Read access (mentioned above)
5. Authorize started tasks to read JES lists.
  
  Important! If you do not want to interfere with your system as described, you can specify the LOAD library in the STEPLIB, but also in the DD card EDCMTF of the C-environment. For more information, see the STEPLIB DD statement in the IBM documentation.
6. The following authorizations are required for the STC user in RACF:
  - OMVS segment
  - ALTER authorization for own data sets (for example, UC4.*)
  - Started tasks require the appropriate authorization to read JES lists
Set up the system environment in the host:
- Adjust the INI file accordingly. It must not use the file attribute NUMBER ON, see Agent z/OS
- Adjust the HEADER.MVS, TRAILER.MVS and RESTART.MVS as required, see Executing Jobs.
Start the Agent:
1. Make sure the Automation Engine is running on the server computer, see Multi-Server Operations.
2. On the host, use start UC4RUN through the system console. An Agent object is automatically created in the system Client 0 and stored in the HOST folder.
3. In AWI, Client 0, verify that the Agent is logged on to the Automation Engine.
  
  Newly logged on Agents are not assigned to a client automatically and can only be viewed in Client 0. Once you have logged in to Client 0, access the Administration perspective and select Agents & Groups.
  
  Assign the new Agent to Clients with the required rights using the Agent object definition. For more information, see Authorizations page.
On the host, quit the Agent's started task through the system console using a MODIFY command, such as modify UC4RUN,end. You can also use the STOP command stop UC4RUN. To stop the agent and all connected Event Monitors you can use the MODIFY command UC4RUN,shutdown.
Create the started task for the Event Monitor.
1. Adjust the INI file of the Event Monitor, see z/OS Event Monitor.
2. Create a separate INI data set for each LPAR UC4.UCXEM25.INI -> UC4.UCXEM25.INI.<sysid>.
3. Create the Automation Engine started task for the Event Monitor.
  
  Example:
  
  //UC4EMRUN PROC
  
  //EVENTM EXEC PGM=UCXEM25,REGION=0M,
  
  //PARM='HEAP(4M,4M,ANY,FREE)/UC4.UCXEM25.INI.&SYSNAME'
  
  //STEPLIB DD DISP=SHR,DSN=UC4.LOADLIB
  
  //SYSPRINT DD SYSOUT=*
  
  //UCEVENT DD DISP=SHR,DSN=UC4.UCEVENT.VSAM.&SYSNAME
4. Create the UCEVENT data set for each LPAR.
  
  Example:
  
  //CRTEMDS JOB ####,'XXX',NOTIFY=&SYSUID,MSGLEVEL=(1,1)
  
  //* Create Data sets for UC4 EventMonitor
  
  //*. -----------------------------------
  
  //UCEVENT EXEC PGM=IDCAMS
  
  //SYSPRINT DD SYSOUT=*
  
  //SYSIN DD *
  
  DEFINE -
  
  CLUSTER ( -
  
  NAME(UC4.UCEVENT.VSAM.SYSNAME) -
  
  INDEXED -
  
  VOLUMES(volume) -
  
  TRACKS(1 1) -
  
  ) -
  
  DATA ( -
  
  NAME(UC4.UCEVENT.VSAM.DATA.SYSNAME) -
  
  KEYS(20 0) -
  
  RECORDSIZE(1024 1024) -
  
  FREESPACE(10 5) -
  
  ) -
  
  INDEX ( -
  
  NAME(UC4.UCEVENT.VSAM.INDEX.SYSNAME) -
  
  )
  
  /*
  
  //* -----------------------------------
  
  //INITVSAM EXEC PGM=IDCAMS
  
  //SYSPRINT DD SYSOUT=*
  
  //OUT1 DD DISP=SHR,DSN=UC4.UCEVENT.VSAM.SYSNAME
  
  //SYSIN DD *
  
  REPRO INFILE(IN1) OFILE(OUT1)
  
  //IN1 DD *
  
  DUMMY
  
  /*
Use the command start UC4EMRUN to start the Event Monitor.
Use the MODIFY command UC4EMRUN,end to end the Event Monitor. In this case, the STC is stopped while the SMF Exit remains active. Upon starting the Event Monitor again, all missed SMF records are processed. You can also use the MODIFY commands UC4EMRUN,shutdown or UC4EMRUN,end. In this case, both STC and SMF are stopped.

Notes:
- If the MVS Extended Console is protected, the RACF authorization READ is required to run the Event Monitor.
- In case the agent is upgraded from a previous version, we recommend reinitializing the UCEVENT and the filter datasets.