Configuring user ID for setting up WML for z/OS

For ease of access control, it is recommended that you use the same user ID for configuring the systems and services of WML for z/OS. Consider creating a multi-purpose <mlz_setup_userid>, grant it required permissions, and customize your z/OS environment for it.

Procedure

If you have not done so, create a multipurpose <mlz_setup_userid>.
You can create the required <mlz_setup_userid> in different ways. For example, you can customize and run the following sample JCL job to create the ID:
```
//CREATE JOB (0),'WMLZ RACF',CLASS=A,REGION=0M,
//             MSGCLASS=H,NOTIFY=&SYSUID
//*------------------------------------------------------------*/
//RACF     EXEC PGM=IKJEFT01,REGION=0M
//SYSTSPRT DD SYSOUT=*
//SYSTSIN  DD *
ADDGROUP <mlz_group> OMVS(GID(<group-identifier>)) OWNER(SYS1)
ADDUSER <mlz_setup_userid> DFLTGRP(<mlz_group>) OMVS(UID(<user-identifier>) HOME(/u/<mlz_setup_userid>) -
PROGRAM($IML_INSTALL_DIR/iml-zostools/bin/bash)) -
NAME('WMLZ ID') PASSWORD(<password>) NOOIDCARD
/*
```
where
- <mlz_setup_userid> is the user ID that you will use to configure and run WMLz.
- <mlz_group> is a RACF® group that you will use to associate WML for z/OS users and manage their access.
- <group-identifier> is the identifier for <mlz_group>.
- <user-identifier> is the identifier for <mlz_setup_userid>. Do not use UID 0 for <mlz_setup_userid>.
- $IML_INSTALL_DIR is the directory where WMLz is installed. The default is /usr/lpp/IBM/aln/v3r1/core.
Allocate a minimum of 500 MB disk space to the home directory for <mlz_setup_userid>.
Create the $IML_HOME directory and subdirectories that WML for z/OS will use to store all configuration, customization, and log files as well as runtime data.
1. Create the $IML_HOME directory. Make sure that $IML_HOME is mounted to a zFS file system with at least 50 GB storage available.
  Tip: Avoid creating or configuring the $IML_HOME directory with automount management. Automount might unmount a directory if it is not referenced for a period of time. Any unplanned unmount of the $IML_HOME directory will cause WML for z/OS services to fail.
2. If you use another user ID to create the $IML_HOME directories, make sure to change the directory owner to user ID <mlz_setup_userid> by issuing the following command:
```
chown –R <mlz_setup_userid>:<mlz_group> $IML_HOME/
```
3. To allocate zFS data set for $IML_HOME that is larger than 4GB, make sure that you specify DFSMS data class with extended format and extended addressability.
Configure your z/OS UNIX shell environment for <mlz_setup_userid>
1. Copy the $IML_INSTALL_DIR/alnsamp/profile.template directory into $HOME/.profile for <mlz_setup_userid>.
2. Customize the following environment variables in the profile template:
  - Set $JAVA_HOME to the directory of IBM® Java installation.
  - Set $WLP_INSTALL_DIR to the directory of IBM WebSphere® Application Server for z/OS Liberty installation.
  - Set $IML_HOME to a user-defined directory where WML for z/OS configurations and logs are stored.
  - Set $IML_INSTALL_DIR to the directory where WML for z/OS is installed. The default is /usr/lpp/IBM/aln/v3r1/core.
  - Set $IML_JOBNAME_PREFIX to a string that is 1-4 bytes in length as the prefix of a WMLz service jobname. The first byte must be an alphabetic character, and each of the remaining bytes can be an alphanumeric character. A complete jobname for each of the WMLz services is the concatenation of the prefix string that is defined in the $IML_JOBNAME_PREFIX environment variable and the fixed 4-byte suffix that is supplied by the WMLz product. See Customizing the prefix of a WML for z/OS service jobname for instructions.
  - Set $AIE_INSTALL_DIR to the directory where the IBM Z AI Data Embedding Library is located on your z/OS system. The default is /usr/lpp/IBM/aie. Set this variable only if you plan to use the IBM Z Deep Neural Network Library (zDNN) for scoring ONNX models, which leverages the on-chip AI accelerator of z16™.
  - If necessary, set $XL_CONFIG to the xlc.cfg file that is used for enabling the xlc utility in your environment for <mlz_setup_userid>.
    You must properly set up the xlc utility for <mlz_setup_userid> if you plan to import ONNX models into WMLz. You will encounter errors if the utility is not properly configured. See xlc — Compiler invocation using a customizable configuration file for configuration instructions.
Configure <mlz_setup_userid> access to your z/OS UNIX shell environment.
- Permissions required for configuring and starting WMLz:
  - $IML_HOME environment variable included in the user's profile, pointing to the user-defined directory that contains WML for z/OS customizations.
  - Permission to read and write to the $IML_HOME directory.
  - Permission to read and execute to the $IML_INSTALL_DIR and $IML_INSTALL_ENT_DIR directories used by the SMP/E installation.
  - $SPARK_HOME environment variables included in the user's profile.
  - $JAVA_HOME/bin defined in the $PATH environment variable in the user's profile.
  - $IBM_JAVA_OPTIONS environment variable set to -Dfile.encoding=UTF-8 in the user's profile.
    Consider using a customized java.security file if all of the following factors apply to you:
    
    You select JCERACFKS as the keystore type for your WMLz.
    
    The Java security specification ($JAVA_HOME/lib/security/java.security) on the system where your WMLz runs lists IBMJCECCA as the top provider.
    
    Your WMLz does not need to use the resources in the ICSF services.
    In this case, remove the IBMJCECCA provider from your Java security provider list and set $IBM_JAVA_OPTIONS to the updated java.security file:
```
export IBM_JAVA_OPTIONS="$IBM_JAVA_OPTIONS -Djava.security.properties=$IML_HOME/configuration/java.security"
```
  - $_BPXK_AUTOCVT environment variable set to ON in the user's profile.
  - Read access to the RACF BPX.JOBNAME facility class so that you can assign default jobnames with the ALN prefix to the started WMLz services.
  - Read access to the RACF BPX.FILEATTR.PROGCTL facility class when using client authentication for z/OS Spark and Jupyter Kernel Gateway.
  - Read access to resources CSFDSG, CSFDSV, CSFEDH, CSFIQA, CSFIQF, CSFOWH, CSFPKG, CSFPKI, CSFPKX, CSFRNG, and CSFRNGL for ICSF services in the CSFSERV class if your system is CryptoCard-enabled.
- Permissions required for creating, configuring, and starting WMLz scoring service:
  - $IML_HOME environment variable included in the user's profile, pointing to the user-defined directory that contains WML for z/OS customizations.
  - Permission to read and write to the $IML_HOME directory.
  - Permission to read and execute to the $IML_INSTALL_DIR and $IML_INSTALL_ENT_DIR directories used by the SMP/E installation.
  - Permission to read to the $WLP_INSTALL_DIR directory.
  - Permission to execute scripts under the $WLP_INSTALL_DIR directory.
  - $JAVA_HOME/bin defined in the $PATH environment variable in the user's profile.
  - $_BPXK_AUTOCVT environment variable set to ON in the user's profile.
- Permissions required for configuring WMLz scoring service in a CICS® region:
  - $IML_HOME environment variable included in the user's profile, pointing to the user-defined directory that contains WML for z/OS customizations.
  - Permission to read and write to the $IML_HOME directory.
  - Permission to read and execute to the $IML_INSTALL_DIR and $IML_INSTALL_ENT_DIR directories used by the SMP/E installation.
  - $_BPXK_AUTOCVT environment variable set to ON in the user's profile.
Update system resource settings, including CPUTIMEMAX, MEMLIMIT, and ASSIZEMAX values in the OMVS segment of the RACF profile for <mlz_setup_userid>.
If needed, issue the ALTUSER command to update the CPUTIMEMAX, MEMLIMIT, and ASSIZEMAX settings as shown in the following example:
```
ALTUSER <mlz_setup_userid> OMVS(ASSIZEMAX(address-space-size)
     MEMLIMIT(nonshared-memory-size) CPUTIMEMAX(cpu-time))
```
WMLz requires sufficient system memory to function properly. You can use the MEMLIMIT and ASSIZEMAX parameters to control the amount of memory for the address space started by <mlz_setup_userid>. At the minimum, set MEMLIMIT initially to 24 GB or greater and ASSIZEMAX to 1 GB.

WMLz runtimes and services should be considered server processes and require sufficient system CPU to run unimpeded. Consider setting the CPUTIMEMAX parameter to unlimited to ensure uninterrupted WML for z/OS operations.

You can issue the ulimit command in a z/OS UNIX shell session to verify CPUTIMEMAX, MEMLIMIT, and ASSIZEMAX settings. The command returns a message that is similar to the following example:
```
/bin/ulimit -a 
core file         8192b
cpu time          unlimited 
data size         unlimited 
file size         unlimited 
stack size        unlimited 
file descriptors  520000
address space     1048576k
memory above bar  24576m
```
Where
- memory above bar is the value of the MEMLIMIT parameter.
- address space is the value of the ASSIZEMAX parameter.
- cpu time is the value of the CPUTIMEMAX parameter.
See ALTUSER (Alter user profile) and ulimit for more information.
Verify that the required Java is installed on the z/OS system where you will install WMLz and available to <mlz_setup_userid>.

Spark requires IBM 64-bit SDK for z/OS as described in Installing prerequisite hardware and software for WML for z/OS. The default Java installation directory is /usr/lpp/java/J8.0_64 or /usr/lpp/java/J11.0_64. Take note of the path if you set it to something different. Make sure that the installed Java environment is available to WMLz, Spark, and <mlz_setup_userid>.
Verify that your system is properly configured for <mlz_setup_userid> by running the wmlz-configuration-checker.sh script in the $IML_INSTALL_DIR/alnsamp directory.
Run the script with the -preconfig option to check the configuration settings of required software, system environment variables, and user ID as shown in one of the following examples:
```
./wmlz-configuration-checker.sh -preconfig
```
If you don't plan to configure your WMLz with a Python runtime environment, run the script with the -no-python option:
```
./wmlz-configuration-checker.sh -preconfig -no-python
```
Errors or warnings are logged into the $IML_HOME/alnsamp/wmlz-checker-report-<timestamp>.out file. Make sure that you fix the errors and address the warnings and then run the script again.