Preparing for the IWSz Server for AAI Implementation

When installing, upgrading and maintaining solutions on your mainframe environment, usually various system support teams are involved. You will probably have to submit change requests, wait for approvals, and so on.

STC User ID

The primary Server STC and secondary Request STC for each instance of the IWSz Server for AAI require an STC type User ID under which they will execute. Multiple Instances of the IWSz Server for AAI can execute using the same User ID.

The primary Server STC for an instance executes in USS via BPXBATCH running executables from a USS directory. This means that the User ID used to run the primary and secondary STCs must be defined with an OMVS segment associated with the User ID.

It is also recommended to set the $HOME directory for this User ID to the USS directory where you install the IWSz Server for AAI USS executables.

Examples for Defining the STC User ID and the STC Definition

RACF

Define STC User ID

ADDUSER AISTSRVR -
   NOPASSWORD -
   DFLTGRP(STCGROUP) -
   OMVS(UID(n) HOME(/u/users/cai/AISZ) OMVSPGM(/bin/sh)) -
   NAME('IWSz Server for AAI')

Define STARTED CLASS for STCs AITSyyyx and AITRyyyx

RDEFINE STARTED AIT.* -
   STDATA(USER(AISTSRVR) GROUP(STCGROUP) TRUSTED(NO))

ACF2

Define STC User ID

INSERT AISTSRVR NAME('IWSz Server for AAI') STC – 
   JOB TSO -           
   GROUP(OMVSDGRP) -                                                     
   DEPT(dept) DIV(div) 
                                                 
SET PROF(USER) DIV(OMVS)                                              

INSERT AISTSRVR UID(n) -                                              
  HOME(/u/users/cai/AISZ) OMVSPGM(/bin/sh)
/ F ACF2,REBUILD(USR),CLASS(P)
/F ACF2,REBUILD(GRP),CLASS(P)
/F ACF2,OMVS

Define STCs

SET CONTROL(GSO)
INSERT STC LOGONID(AISTSRVR) STCID(AITSyyyx)
INSERT STC LOGONID(AISTSRVR) STCID(AITRyyyx)

/F ACF2,REFRESH(STC)

Top Secret

Define STC User ID

TSS CRE(AISTSRVR) PASS(NOPW,0) – 
   NAME('IWSz Server for AAI') –
   DEPT(dept)
  
TSS ADD(AISTSRVR) GROUP(STCGROUP) UID(n) –
   HOME(/u/users/cai/AISZ) OMVSPGM(/bin/sh) -                  
   DFLTGRP(STCGROUP)

Define STC

TSS ADD(STC) PROCN(AITSyyyx) ACID(AISTSRVR)
TSS ADD(STC) PROCN(AITRyyyx) ACID(AISTSRVR)

USS Data Directory

The IWSz Server for AAI requires an additional USS data directory for each Instance, either as a sub-directory within the $HOME directory or as a separate data directory in USS.

This USS data directory is used to generate the various data files to be delivered to the IWS Connector server using either SFTP or FTP/FTPS. Once each generated data file has been delivered to the IWS Connector, it is deleted from the USS directory to ensure space is available for future data file generation.

As with the data delivery target directory/directories on the IWS Connector, each instance of the IWSz Server for AAI that executes on the same LPAR must have a unique USS directory and a unique zFS volume created and mounted to that USS directory.

It is therefore recommended that the following directory structure and naming conventions be used when creating the USS Data directory for each instance.

/your_prefix_path/Scheduler_ID/AAI_ID

Example:

If the $HOME installation directory is used to also contain the Data Generation USS directory as a sub-directory, then a suitable format could be:

/opt/cai/AISZ/OPCA/AAI

Data Delivery Mechanisms

The IWSz Server for AAI creates various reports and delivers them to the target location via SFTP, FTP or Secure FTP (FTPS using FTP/SSL or FTP/TLS). The target location is a directory or directories on the IWS Connector server. This directory or directories must already exist before implementing an instance of the IWSz Server for AAI.

To make sure that the data delivery from each instance of the IWSz Server for AAI is stored in a unique directory on the IWS Connector, we recommend the following directory path structure and naming conventions on the target directory/directories:

/your_path_prefix/LPAR/Scheduler_ID/directory_name

Examples:

aai/data/ZM1R/OPCA/EVENTS

aai/data/IWS/OPCA/DEFS

Where:

aai/data = your_path_prefix

ZM1R = LPAR

OPCA = Scheduler ID

EVENTS and DEFS = directory_name

Using SFTP

Data is delivered from the client (the IWSz Server for AAI) through a file transfer to the target distributed server (the AAI server) using an SSH (secure shell) connection. Two user IDs are involved in the connection: the client user ID and the target user ID. Before the connection can happen and, therefore, the data can be delivered, the SSH connection must be authenticated by the daemon on the AAI server.

The authentication of the IWSz Server for AAI can be done in two different ways:

• Using a clear text public/private key pair

• Using a digitally signed certificate created on the client side (the mainframe)

In either case, the public key is then transferred to the AAI server. The public key is saved in the authorized_keys file of the AAI server User ID; it is used to verify that the incoming connection is from a trusted “client” system that uses a trusted User ID who can log in as the AAI server User ID.

Authenticate Using a Clear Text Public/Private Key Pair

The public/private key pair is created using the CUSTLIB member AIZJGKEY. This JCL uses BPXBATCH to execute the ssh-keygen command to generate an rsa type 2 with no passphrase. It stores the rsa type 2 in the $HOME/.ssh sub-directory.

The .ssh subdirectory must already be available in the $HOME directory before running the AIZJGKEY JCL. As the ssh-keygen command generates the authentication keys for the User ID under which the BPXBATCH program is executed, the AIZJGKEY JCL is provided as an STC PROC to put into the STC procedure library. It uses the Primary STC name and it is executed by starting the STC. This then runs under the assigned STC User ID to generate the correct key pair for that User ID.

The AIZJGKEY JCL is created with the $HOME/.ssh directory pre-set in the PARM= parameter to the value of the directory path on the first full install. When deploying additional instances to other LPARs, the value of the directory path may need to be changed manually to reflect the path value for the new LPAR if that is different from the original install path.

The resulting id_rsa.pub file created in the $HOME/.ssh sub-directory must then be transferred as a text file to the AAI server machine and added to a file called authorized_keys. This file is located in the $HOME/.ssh sub-directory of the AAI server User ID that will be used by the IWSz Server for AAI when initiating the SFTP connection (ssh logon).

Authenticate Using a Digitally Signed Certificate

A Certificate Authority (CA) creates and signs a certificate for the STC User ID and LPAR host under which the IWSz Server for AAI instance will execute. This certificate must then be installed into a SAF Security based Key Ring using an X.509 certificate as the container. For information about how to create SAF Security based Key Rings for use with OpenSSH certificates and exporting the public key, please refer to the IBM z/OS OpenSSH User Guide. For information about how to create and use Key Rings, and about the commands associated with them, please refer to the official documentation of your SAF security product.

To support Key Ring certificates in the authentication process, you must create a zos_user_ssh_config file in the $HOME/.ssh sub-directory that specifies where the certificate is stored in an IdentityKeyRingLabel statement.

You can then export the certificate stored in a Key Ring using one of the following:

• Your SAF Security commands

• The ssh-keygen –e and ssh-keygen –i command formats

In either case an OpenSSH format public key is created. As with the clear text public/private key pair methodology, you must then transfer the resulting public key obtained from the Key Ring as a text file to the AAI Server machine. You must add it to a file called authorized_keys located in the $HOME/.ssh sub-directory of the AAI Server User ID .that will be used by the “client” Server for AAI when initiating the SFTP connection (ssh logon) to the “target” server.

Preparing the USS for SFTP Data Delivery

When using SFTP as the data delivery mechanism, an additional USS data directory is required, either as a sub-directory within the $HOME directory or as a separate directory in USS.

This USS data directory is used for copies of the various data files to be delivered to the AAI server which cannot transfer directly from the z/OS datasets where the data files are created. These copies are made available to this directory prior to their transfer via SFTP. The data file copy in the USS Data directory is deleted after it has been transferred via SFTP.

As with the data delivery directory / directories on the AAI server, each instance of the IWSz Server for AAI that executes on the same LPAR must have a unique USS directory for the data copy process prior to the SFTP transfer. It is therefore recommended that the following directory structure and naming conventions be used when creating the USS Data directory for each instance.

/your_prefix_path/Scheduler_ID/AAI_ID

Example:

/opt/cai/AISZ/OPCA/AAI

Using FTP

FTP is often the simplest way of establishing the connection. It only requires a User ID and password combination that is sent to the FTP server software running on the AAI server. The AAI server opens the port connection if authentication is successful, allowing the transfer of data. However, regular FTP is often not allowed at many sites for security reasons:

• Data transfer occurs without any encryption.

• To avoid connection failures, the password is usually set to be non-expiring.

Using FTPS

This is the IBM z/OS preferred methodology. It supersedes FTP/SSL.

With Secure FTP (also known as FTPS or FTP/TLS), authentication happens at a host level by Transport Layer Security (TLS). The AAI Server provides the client host with certificate authentication that is matched with a certificate stored in a Key Ring at the client host (the mainframe). This validates that the AAI Server is what it says it is.

Requirement

The IWSz Server for AAI does not support implementing TLS security directly itself. It requires that Application Transparent Transport Layer Security (AT-TLS) is implemented at the network level. For information about how to implement AT-TLS in your environment, please refer to the IBM z/OS Communications Server: IP Configuration Guide. Your Network team will have to set up an FTPS-based connection between the IWSz Server for AAI and the AAI server.

Considerations for FTP and FTPS

Depending on how FTP or FTPS is implemented in your environment, consider the following:

• A password may or may not be required.

• A non-standard IP Port can be used and/or an alternative FTP configuration file may need to be referenced.

  The IWSz Server for AAI system supports the definition of a non-standard IP Port, the definition of an alternative FTP configuration file and optional password specification.

• FTP and FTPS support delivery of the data files directly from the z/OS datasets into which the data is created by the IWSz Server for AAI. This eliminates the need for a USS data directory and the intermediate data copy process that is required when using SFTP as the data delivery methodology.

zFS Volume Sizing

Each instance of the IWSz Server for AAI requires a zFS volume defined and mounted to a specified zFS Data Path in USS. The IWSz Server for AAI generates the required data files directly into that USS directory. The zFS volume dataset is created when defining an instance of the IWSz Server for AAI using the IMS. The USS directory used for the zFS Data Path must be manually created before the zFS volume can be mounted.

Some of the data files generated by the IWSz Server for AAI can be quite large. To allow for expansion in the event of data volume growth, do the following:

• Specify the zFS volume size accurately from the beginning.

• Define it with the AGGGROW attribute. When using the IMS to define the zFS the AGGGROW parameter is used when formatting the zFS.

The data files that should be evaluated to determine the initial size of the zFS volume are the defs, track and cpop files which are generally the largest of the data files being generated. The largest of these data files should be used to set the initial size of the zFS volume, however consideration must be made for a larger zFS volume size if the Definition Data Generation process and the Current Plan process are expected to run at around the same time of day, and thus generate their data files at the same time.

To determine the size of each of these three data files, execute the following programs in batch, pointing the specified Output DD name at a z/OS dataset. Use the size of the largest plus 20%, in cylinders, as the initial size for defining the zFS volume.

For the execution of the EQQYCAIN program the parameter includes the ssid value which should be set to the IWSz Sub-System ID of the source IWSz system.

defs file – used to hold Application and Operation definitions

• Program to execute

  EQQYCAIN,PARM=’ssid,MSGOFF’

• SYSIN Input

  ACTION=OPTIONS,BL=Y,BLPRT=Y,ERROR=Y;

  ACTION=LIST,RESOURCE=ADCOM,ADID=*,TYPE=A;

  ACTION=LIST,RESOURCE=ADCOM,ADID=*,TYPE=G;

  ACTION=LIST,RESOURCE=RGCOM,RGID=*;

• Output DD Name

  BATCHL

• DCB format

  FB    80

 

 

 

 

track file – used to hold History Tracking data from the EQQTROUT dataset

• Program to execute

  EQQBATCH,PARM=’EQQAUDIT’

• SYSIN Input

  TRL

• Output DD Name

  AUDITPRT

• DCB format

  FBA    133

 

CPOP file – used to hold the Current Plan Report

 

• Program to execute

  EQQYCAIN,PARM=’ssid,MSGOFF’

• SYSIN Input

  ACTION=OPTIONS,BL=Y,BLPRT=Y,ERROR=Y;

  ACTION=LIST,RESOURCE=CPOPCOM,ADID=*.

• Output DD Name

  CPOP

• DCB format

  FB    80

Next Steps

You are ready to start implementing the IWSz Server for AAI. Use the Implementation Checklists (IWSz Server for AAI) to have the necessary data at hand when ding so. The following topic guides you through the implementation process:

• Implementing an Instance of the IWSz Server for AAI

See also:

• Installing the IWSz Server for AAI
• Configuring an Instance of the IWSz Server for AAI
• Managing an Instance of the IWSz Server for AAI
• Schedulers