Preparing for the CA7 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.

This page provides details about the activities you must take care of before installing and implementing an instance of the CA7 Server for AAI.

STC User ID

The primary Server STC and secondary Request STC for each instance of the CA7 Server for AAI require an STC type User ID under which they will execute. Multiple Instances of the CA7 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 CA7 Server for AAI USS executables.

Examples for Defining the STC User ID and STC Definitions

These are examples for defining the STC User ID and the two STC definitions. Replace the yyyx value with the Instance specific code and the OMVS UID(n) value as appropriate for your installation. The HOME value should be set to the installation USS directory.

RACF

Define STC User ID

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

Define STARTED CLASS for STCs AI7Syyyx and AI7Ryyyx

RDEFINE STARTED AI7.* -
   STDATA(USER(AIS7SRVR) GROUP(STCGROUP) TRUSTED(NO))

ACF2

Define STC User ID

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

INSERT AIS7SRVR 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 STC

SET CONTROL(GSO)
INSERT STC LOGONID(AIS7SRVR) STCID(AI7Syyyx)
INSERT STC LOGONID(AIS7SRVR) STCID(AI7Ryyyx)

/F ACF2,REFRESH(STC)

Top Secret

Define STC User ID

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

Define STCs

TSS ADD(STC) PROCN(AI7Syyyx) ACID(AIS7SRVR)
TSS ADD(STC) PROCN(AI7Ryyyx) ACID(AIS7SRVR)

CA7 User ID

The definition data that AAI requires from CA7 is obtained through various executions of CCITERM (CAL2X2WB) program. This program issues a series of commands to CA7 to extract the data from its database.

To be able to issue commands to CA7, a CA7 User ID and a password (if required) must be made available to the CA7 Server for AAI. The User ID and password are then provided during the configuration of the instance via the IMS. If required, the password is encrypted

This User ID could be the following:

The STC User ID itself, defined in the security system
A separate User ID specifically created for use by the CA7 Server for AAI

This User ID must have access to CA7 and the following output type commands that will be issued via CCITERM:

LJOB,JOB=*,LIST=ALL

LDSN,DSNBR=DS*

LISTDIR,DSN=*SCAL*

PRINT,SCAL=xx,YEAR=yy

If CA7 has been configured to use Job Level security access control, then the CA7 User ID must be able to read all job definitions in the CA7 database. For this purpose, grant the CA7 User ID access level CA7 UID=255 by using the /PROF,R=uidname command.

USS Data Directory

The CA7 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 AAI server using either SFTP or FTP/FTPS. Once each generated data has been delivered to the AAI server, it is deleted from the USS directory to ensure space is available for future data file generation.

As with the data delivery target directory on the AAI server, each instance of the CA7 Server for AAI that executes on the same LPAR must have the following:

A unique USS directory
A unique zFS volume created and mounted to that USS directory

Use the following directory structure and naming conventions 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/CA71/AAI

Important!

To avoid delivery failures due to USS space availability, ensure that the USS data directory has sufficient space to hold the largest of the data files that will be delivered to the AAI server. For information about how large the zFS volume mounted to the USS data directory should be for an instance, see zFS Volume Sizing.

Data Delivery Mechanisms

The CA7 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 on the AAI server. This directory must already exist before implementing an instance of the CA7 Server for AAI.

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

/your_path_prefix/LPAR/Scheduler_ID/

Example:

aai/data/SYSP/CA71

Notes:

Refer to the IBM documentation for detailed information on configuring the chosen Data Delivery mechanism.
Involve mainframe Network and Security people for advice on implementing the Data Delivery mechanism in your specific environment.
For all Data Delivery mechanisms, the CA7 Server for AAI is considered the “client” requesting the data transfer. Compatible transfer “server” software must be installed and active on the “target” distributed server. For SFTP transfers, an ssh daemon must be active. For FTP or FTPS transfers, an FTP server process must be running.
In most cases, a User ID on the “target” distributed server will be required which has read/write permissions to the “target” location. This is the User ID that will be used by the CA7 Server for AAI to initiate the “client” connection to the “target” distributed server.

Using SFTP

Data is delivered from the client (the CA7 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 CA7 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 can be 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 STC User ID $HOME/.ssh sub-directory.

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 CA7 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 CA7 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 ans 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 a 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.

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 CA7 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 CA7 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 CA7 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.

zFS Sizing

Each instance of the CA7 Server for AAI requires a zFS volume defined and mounted to a specified zFS Data Path in USS. The CA7 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 CA7 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 CA7 Server for AAI can be quite large. To handle unexpected expansion during execution, make sure of the following:

The zFS volume size is initially specified fairly accurately
The zFS volume is defined with the AGGGROW attribute to allow for expansion in the event of data volume growth.

When using the IMS to define the zFS, the AGGGROW parameter is used when formatting the zFS.

The LDSN and LJOB data files are usually the largest data files to be generated. Use the largest of them to determine the initial size of the zFS volume. To determine the size of these two data files, execute the following programs in batch, pointing the specified Output DD name at a very large z/OS dataset. Use the size of the largest of the two datasets plus 20%, in cylinders, as the initial size for defining the zFS volume.

LJOB file

Used to hold CA7 Job, Scheduling, Dependency and Trigger definitions.

Program to execute

CAL2X2WB,PARM=’,ca7id’
SYSIN Input

/LOGON,userid,password

LJOB,JOB=*,LIST=ALL

/LOGOFF
Output DD Name

SYSPRINT
DCB Format

FBA 133

LDSN file

Used to hold CA7 Dataset definitions.

Program to execute

CAL2X2WB,PARM=’,ca7id’
SYSIN Input

/LOGON,userid,password

LDSN,DSNBR=DS*

/LOGOFF
Output DD Name

SYSPRINT
DCB Format

FBA 133

Next Steps

You are ready to start implementing the CA7 Server for AAI. Use the Implementation Checklists (CA7 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 CA7 Server for AAI