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.

Data Delivery

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 is stored in a unique directory on the AAI server, we recommend the following directory path structure and naming conventions on the target directory/directories:

/your_path_prefix/Scheduler_type/LPAR/Scheduler_ID/directory_name

Examples:

aai/incomingdata/IWS/ZM1R/OPCA/EVENTS

aai/incomingdata/IWS/ZM1R/OPCA/DEFS

Where:

aai/incomingdata = your_path

IWS = Scheduler_type

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.

Dataset Sizing

Each instance of the IWSz Server for AAI requires a set of execution datasets that generate and store the data required by AAI. These datasets are reused every time the IWSz Server for AAI instance creates the next iteration of the data. These datasets are created when defining an instance of the IWSz Server for AAI from the IMS.

Sizing IWSz Instances

Five of the AAI required IWSz data files can potentially be quite large because each data file is generated to its own intermediate execution dataset. However, the SRVRRPTS execution dataset that holds Event Data, given that Event Data Recovery is limited to the data available in the IWS/z JTARC dataset, the size of this can be set to the same space allocation as used by the IWS/z JTARC dataset.

For the execution of the EQQYCAIN program the parameter includes the ssid value which should be set to the IWS/z Sub-System ID of the target IWS/z system.

The following are the datasets for the five IWSz data files.

SRVRRPTS dataset – used to hold extracted Event data in each Cycle of processing
Set the size based on the number of cylinders used by the JTARC dataset

SRVRJARC dataset – used to provide a Pseudo JTARC dataset containing JT Log data
Set size equivalent to 2 times the number of cylinders used by a single JTnn dataset

 

ADDDRPT2 dataset – 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

 

CPOPRPT1 dataset – 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

 

CPOPRPT2 dataset – 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