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.

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.

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

Data Delivery

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

Example:

aai/incomingdata/CA7/SYSP/CA71

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 is created in 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 typ 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 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.

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

• FTP and FTPS support delivery of the data files directly from the z/OS datasets into which the data is created by the CA7 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 CA7 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 CA7 Server for AAI instance creates the next iteration of the data. These datasets are created when defining an instance of the CA7 Server for AAI from the IMS.

The amount of data generated by each instance of CA7 for AAI will vary. The datasets that store the generated data must be sized accurately to avoid dataset space failures. For this purpose, it is recommended that you perform a dataset sizing exercise for each of the execution datasets used for storing the generated data.

Sizing Exercise

1. Execute the relevant scheduler program as a batch job.

2. Point the Output DD Name to a very large dataset (for example, 2,500 cylinders) allocated in the batch job.

3. Check how much of the space is used after the job has run.

4. Repeat for each execution dataset.

Sizing CA7Instances

Three of the AAI required CA7 data files can potentially be quite large, with two instance execution dataset being used to hold these data files:

• ADDDRPTS execution dataset

  Two reports are generated sequentially into the dataset. For sizing purposes execute the batch job twice, once for each SYSIN Input command. Use the larger of these two executions for the sizing exercise.

  For the execution of the CCITERM (CAL2X2WB program), the parameter must specify the CCI Receiver name for the CA7 system. This is usually the CA7 ID (CA71 – CA78). However, this value may be overridden by the SVCNO statement, XTMNAME= parameter specified in the CA7 INIT Deck.

• SRVRRPTS event data dataset

  For the event data generated to the SRVRRPTS dataset, the sizing details below assume that a maximum of 1 day of event data will be generated in a single data file, and that only when doing an Event Recovery during start-up of the instance. For CA7 instances, Event Recovery uses available History Log datasets. These datasets can potentially contain many days’ worth of data. It is assumed that the CA7 Server for AAI is unlikely to be down for such an extended period of time that more than a day of event data recovery may be needed.

The example below provides the following:

• Details of the Scheduling program that needs to be executed

• The input command(s) used to generate the required data

• The DD Name of the output file used as AAI data

• The DCB Format of that output file for allocating the very large dataset used to determine the size required for the equivalent instance execution data set.

 

SRVRRPTS dataset – used to hold Event data
Program to execute		SASSHIS8
				    0    1    1    2
                               ....5....0....5....0
SYSIN Input			70        01DAY
Output DD Name		        SYSLIST
DCB format			FBA	133

ADDDRPTS dataset – used to hold LDSN AND LJOB data – execute twice
Program to execute		CAL2X2WB,PARM=’,CA7_ID’	(aka CCITERM)
SYSIN Input	1		LDSN,DSNBR=DS*
		2		LJOB,JOB=*,LIST=ALL
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

See also:

• Installing the CA7 Server for AAI

• Configuring an Instance of the CA7 Server for AAI

• Managing an Instance of the CA7 Server for AAI

• Schedulers