2 CDA configuration for cloud storage

Cloud Data Access (CDA) must be configured to provide information about and access to the cloud provider(s) that are used by OAM for cloud storage.

2a CDA Panel Library

Ensure that SYS1.DFQPLIB is part of the ISPPLIB concatenation or that the following members located in SYS1.DFQPLIB are added to an ISPPLIB library:

GDKAPPOP
GDKAUTHK
GDKAUTHL
GDKAUTHP
GDKMAINP
GDKOBJAC
GDKOBJAL

A RACF (or equivalent) profile should be created to ensure only authorized users have access to these members.

2b Alter Configuration File

The CDA configuration file, config.json, contains settings that alter CDA behavior. Currently, the only value is related to logging and error capture.

It is recommended to leave the “log-level” setting at its default value “NONE”. If it becomes necessary, OAM or CDA support can request that this value be changed to assist with problem diagnosis.

2c Alter Cloud Provider Definition File

The cloud provider definition file IBMCOS.json contains fields and values which describe settings and supported operations related to the cloud storage provider. There can be multiple provider definition files which can be used to define different cloud storage providers or multiple versions of the same provider (For example, an east and west region of the same provider). The following keys and values are described in detail below:

name: Required. The name of the cloud provider which is utilized by the cloud key entry panel and OAM; must match the filename.
host: Required. The endpoint URL for the cloud provider.
port: Required. The endpoint URL port number.
region: Required for “AWS4” authentication models. The name of the region name to be used.
httpMechanism: Required. Only HTTPS is supported.
sslVersion: Optional. Valid values are “TLSV12”, “TLSV11”, “TLSV10”, and “SSLV3”. It is recommended to set the highest version supported by the cloud storage provider. If no key pair is specified, SSL is used but no security version is sent on requests.
sslCiphers: Optional. A string value that represents the specification of the cipher suites to be used by SSL. The recommendation is to remove this key pair unless a specific cipher suite is required by the cloud storage provider.
receiveTimeout: Optional. The number of seconds an open SSL socket waits for incoming requests. Default value is 300.
sendTimeout: Optional. The number of seconds an open SSL socket waits for outgoing requests. Default value is 300.
cloudServerTZ: Optional. Valid value is a time zone abbreviation plus optional offset. For example, “UTC” or “EST+2”. This time zone is used when generating timestamps for cloud requests and should match the cloud provider. Default value is “GMT”.
IPStack: Optional. A 1-8 character local z/OS TCP/IP stack name to be used when communicating with the cloud provider.
authentication: Required. Set to “AWS4” to utilize the S3 API.

All other entries under the “supportedOperations” key should not be altered.

2d Add Cloud Provider Keys

Prior to starting this step, ensure that the security (or storage) administrator who is entering the cloud provider keys has sufficient authority to write to the gdkkeyf.json file (/OAM_home_dir_name/gdk/gdkkeyf.json) and the CSFKEYS profile for resources beginning with GDK. For more information, see 1e Secure the OAM Home Directory and 1f Configure the CSFKEYS general resource class in 1 Security configuration for cloud storage.

From the TSO command line, issue the following command:

EX ‘SYS1.SAXREXEC(GDKAUTHP)’

This starts a CDA panel where the S3 key pair is encrypted and saved.

Select the cloud provider associated with the key pair being added by entering the associated number under the “Select Cloud Provider” heading.
Enter the RACF (or equivalent) user id associated with OAM into the UserID field under the “Encryption Parameters” section.
If this key pair is intended to be used with a specific bucket, enter a ‘/’ followed by the bucket name in the Resource field under the “Encryption Parameters” section. Otherwise, simply enter a ‘/’ to indicate that this key pair is valid for any bucket associated with this cloud provider.
Both specific and generic keys can be added and CDA attempts to utilize specific keys tied to buckets before utilizing the generic key for the provider.
Note: Only 1 generic key is used per provider. If a second is entered, it overwrites the first.
Press Enter to save the values.
Enter an ‘O’ on the top Option line to continue to the next panel.
Enter the Key and Secret key values into the associated fields under the “Authorization Parameters” section. Press Enter. The characters are not echoed to the screen and are displayed as * when enter is hit.
Enter an ‘S’ on the top Option line to encrypt and save the key pair.

Note: The first time this panel is executed, the user can receive the following warning messages:

ERROR: getpwnam() error: EDC5121I Invalid argument.
ERROR: getpwnam() error: EDC5129I No such file or directory.

This behavior is expected because the UserID field has not yet been populated. Once the OAM user id created in 1 Security configuration for cloud storage, subsection 1b Create RACF OAM User and Group has been specified here at least one time, the warning messages are no longer displayed.

2e Delete Cloud Provider Keys (Optional)

From the TSO command line, issue the following command:

EX ‘SYS1.SAXREXEC(GDKAUTHP)’

This starts a CDA panel where the S3 key pair can be deleted.

Select the cloud provider associated with the key pair being removed by entering the associated number under the “Select Cloud Provider” heading.
Enter the RACF (or equivalent) user id associated with OAM into the UserID field under the “Encryption Parameters” section.
Enter an ‘L’ on the top Option line.
Enter a ‘/’ next to the key to be removed.
Enter a ‘1’ to confirm the delete action.

2f Backup Cloud Data Access Files

Once Cloud Data Access (CDA) has been configured, it is strongly recommended that an OAM administrator make a backup of all the files contained within the /OAM_home_dir_name/gdk directory.