Performing the BMC AMI Cloud agent installation

Task 1: To allocate and mount the ZFS file system

Create a dedicated ZFS file system for the BMC AMI Cloud Agent installation and mount point for the new ZFS, as shown in the following JCL. Edit the JCL using your site’s standard naming convention for the mount point, ZFS, and volume serial number (if it is not managed by the SMS). 

To automatically and permanently mount the ZFS after an IPL, add the mount command to the BPXPRMxx, as shown in the following example: 

Task 2: To upload the BMC AMI Cloud agent TAR file to the mainframe

Use an FTP utility to upload the BMC AMI Cloud agent’s installation TAR file to the BMC AMI Cloud directory created in the previous step. Use passive FTP mode (if supported). You must upload the TAR file in binary mode as shown in the following example: 

Task 3: To extract the agent files from the TAR file

Use the TAR command in the z/OS UNIX shell to extract the agent files. During extraction, all agent files are saved in the same directory. Only users with the following permission can run the agent files in the FACILITY class:

• BPX.FILEATTR.APF ACC(READ)
• BPX.FILEATTR.PROGCTL ACC(READ)
• BPX.FILEATTR.SHARELIB ACC(READ)

The directory name usually includes the agent’s release number. We recommend creating an alias that does not include the release number for the directory. This makes future upgrades more transparent, as shown in the following example: 

Task 4: To create and populate the configuration directory

Create and copy the BMC AMI Cloud sample configuration directory by using the following commands: 

Task 5: To create a program-controlled version of PAX

The BMC AMI Cloud z/OS UNIX files backup uses PAX. To create a program-controlled version of PAX, use the following commands: 

Task 6: To install the BMC AMI Cloud Command Line Interface

You can use the BMC AMI Cloud CLI (command line interface) as an interface for issuing BMC AMI Cloud commands from TSO / JCL. Use the following commands to install this CLI by creating a listener directory under the agent’s main path: 

Task 7: To copy the BMC AMI Cloud libraries from USS to PDS

Edit and submit the JCL CPY#PDS located in /usr/lpp/model9/agent/installation/ to create the BMC AMI Cloud LOADLIB, SAMPLIB, and EXEC PDS files.

Customize the M9CLI rexx in the EXEC PDS to match installation standards: 

Copy the M9CLI EXEC to your site’s local EXEC library.

Task 8: To define the agent to RACF

Use the sample JCL M9USERST in the SAMPLIB PDS to define the security settings required by the agent. 

(Optional) To use the RACF TRUSTED attribute

By default, the M9USERST JCL contains a definition for the M9USER with the OPERATIONS attribute. BMC AMI Cloud also supports the RACF TRUSTED attribute when extended auditing is required. To perform this change follow the steps below:

1. Remove OPERATIONS from ADDUSER M9USER command in the M9USERST JCL.
2. Add TRUSTED(YES) attribute to all RDEFINE STARTED commands within the STDATA section. For example, RDEFINE STARTED M9AGENT.** STDATA(USER(M9USER) GROUP(SYS1) TRUSTED(YES))

3. Add an RDEFINE statement for the life cycle procedure as the TRUSTED attribute. This attribute is supported only for stated tasks.

   RDEFINE STARTED M9LIFECY.** STDATA(USER(M9USER) GROUP(SYS1) TRUSTED(YES))

Submit the JCL and verify that all the commands were performed. If necessary, review the output.

Task 9: To customize the BMC AMI Cloud agent start procedure

Copy the sample JCL M9AGENT from the SAMPLIB PDS to a local PROCLIB member, and update the variables in the JCL as follows:

¹ You can use CONF_HOME to activate more than one agent in the same LPAR, allowing each agent to use the same BMC AMI Cloud installation files and libraries but have a different configuration directory. We recommend that you have one agent per LPAR and point all agents in the same GRS-complex to the same BMC AMI Cloud complex. However, additional agents in the same LPAR might be required in the following scenarios:

• You are using a sub-plex.
• You have both development and production environments.
• You are pointing the agents to a different cloud storage.

CONF_HOME must precede the stdenv-main.sh statement. 

Task 10: To update the BMC AMI Cloud agent configuration

Before starting the agent, update the model9-stdenv.sh and agent.yml configuration files located in /usr/lpp/model9/conf. For more information, see Updating-the-BMC-AMI-Cloud-agent-configuration-files.

(Optional) Task 11: To obfuscate the object storage credentials

To prevent the object storage secret key from appearing in clear text within the configuration files, you can obfuscate it.

Use the obfuscated object storage secret key that was produced during the server installation. When using the obfuscated secret, add the following setting to the agent.yml file.

Task 12: To update the BMC AMI Cloud agent license

Update the license file at /usr/lpp/model9/conf/model9-licenses.txt. The file can accommodate several licenses, for example, the license of all the LPARS in the sysplex and the Disaster Recovery site’s license.

Write each license on a separate line. Comments should be preceded by a # sign.

When multiple licenses are specified in the file, the CPUID must correlate with the CPUID of the executing LPAR. The license with the latest expiration date is used.

The details of the license to be used are displayed in the agent’s log and in the UI. If the agent cannot find a valid license, an error message is displayed as a WTO. The full error message is available in STDOUT.

(Optional) Task 13: To secure the agent-server communication

By default, the agent accepts requests from trusted clients by using a self-signed certificate generated by BMC AMI Cloud. In a production environment, we recommend replacing the certificate with a signed organizational CA certificate.

For more information, see Securing-the-server-to-agent-communication.

Task 14: To install automatic recall

You can use the BMC AMI Cloud automatic recall intercept to recall archived files from within z/OS in a transparent manner. To install the automatic recall intercept:

1. Update the PROGxx configuration by adding the following statements: 

   APF ADD DSNAME(SYS2.MODEL9.V282.LOADLIB) SMS
   LPA ADD DSNAME(SYS2.MODEL9.V282.LOADLIB) MOD(ZM9CPTN)
   LPA ADD DSNAME(SYS2.MODEL9.V282.LOADLIB) MOD(ZM9S26X)
   EXIT ADD EXITNAME(ZM9P_S026) MOD(ZM9S26X) PARM('M9ARCH')

2. Apply the changes by using the following operator command from any console: 

   SET PROG=xx

   Important

   To enable the intercept and exit to function properly, you must load them to the dynamic LPA. Do not use MLPA or PLPA to load the modules.

3. Copy the M9HOOK and M9UNHOOK JCL from the SAMPLIB PDS to a local PROCLIB member. Customize the M9HOOK JCL accordingly and activate it by using the following command: 

   S M9HOOK

   Important

   Add the M9HOOK JCL to your standard IPL process.

4. If an existing BMC AMI Cloud intercept has been uninstalled, then you must load a new copy of the ZM9CPTN module to the dynamic LPA by using the following command: 

   SETPROG LPA ADD DSNAME=SYS2.MODEL9.V282.LOADLIB MOD=ZM9CPTN

5. If you are using another data management product together with BMC AMI Cloud Data, add the following DD statement to the other product’s procedure to avoid collisions: 

   //ZM9$NORC DD DUMMY
6. Restart the address space after applying the DD.

Task 15: To update the life cycle management JCL

The BMC AMI Cloud life cycle management JCL is responsible for automatically deleting data sets (archives, backups and imports) that have expired. A sample JCL, M9LIFECY, is available in the BMC AMI Cloud SAMPLIB PDS.

1. Grant your site scheduler permission for surrogate access to the M9USER: 

   RDEFINE SURROGAT M9USER.SUBMIT UACC(NONE)
   PERMIT M9USER.SUBMIT CLASS(SURROGAT) ID(<scheduler>) ACC(READ)
   SETR REFRESH RACLIST(SURROGAT)

2. Update the variables in the life cycle management JCL as follows: 

   Variable	Update
   DD STEPLIB	BMC AMI Cloud installation LOADLIB
   PWD environment variable	BMC AMI Cloud agent’s installation path

3. To submit the life cycle management JCL in the simulate mode, set --simulate to yes.
   The life cycle management JCL lists all the data sets that would have been deleted without actually deleting them.
4. To submit the life cycle management JCL in the initial mode, set --simulate to no or remove.
   The life cycle management JCL scans all archived data sets with expiration dates in the past up until today’s date. The next time the life cycle runs, it will resume where the previous process ended.

5. (Optional) To set M9LIFECY to use the RACF TRUSTED attribute instead of OPERATIONS, define the JCL as a started task and replace the M9LIFECY's JOB card with //M9LIFECY PROC. 

   Important

   Schedule the life cycle management JCL daily via the local site scheduler.

Task 16: To start the BMC AMI Cloud agent

Start the agent from any console by issuing the following command: 

Verify that the agent was started successfully. The following messages should appear: 

(Optional) Task 17: To configure the Remote Server API M9SAPI

You can use the optional Remote Server API feature to run BMC AMI Cloud policies from within z/OS by using standard JCL. To enable the Remote Server API feature:

1. Copy the sample JCL PROC M9SAPI from the SAMPLIB PDS to a local PROCLIB file and edit the procedure according to the instructions in the file. You can use the JCL M9SAPIJ sample to run a policy.
2. The Remote Server API uses HTTPS to communicate with the server.
   • If a trusted certificate is not defined for the server, set VRFYCERT=NO in the M9SAPI procedure to skip certificate validations.

   • If a valid certificate is defined, make sure that the user running the M9APIJ has the correct SAF keyring defined to enable validation of the server certificate. You can use the SAPI_KEYRING_NAME setting defined in the sample model9-stdenv.sh configuration to specify the keyring name. 

     Important

     Communications between the Remote Server API and the BMC AMI Cloud Server are encrypted, regardless of the VRFYCERT value.

3. When verifying the certificate used by the Remote Server API, you must define it for a Resource Access Control Facility (RACF) by using a keyring.

(Optional) Task 18: To configure ISPF to use M9ARCH as the ML2 default volume

ISPF allows the definition of only one level 2 migration volume. The default migration volume is MIGRAT. To use the BMC AMI Cloud automatic recall function, you must set the default volume to M9ARCH by using the ISPF Configuration utility. Failing to change the migration volume results in the following errors on ISPF panel 3.4:

To change the default ISPF settings:

1. Start the ISPF Configuration utility (TSO ISPCCONF) and select the site defined in the configuration table.
2. To modify the existing table, select Option 1.
3. Change the Volume for Migrated Data Sets name to M9ARCH, the default BMC AMI Cloud archive volume name.
4. Save the settings.
5. Review the newly created configuration table file.

Then either create and install the SMP/E USERMOD containing the new configuration table or create a load module that resides on a shared library containing the ISPF settings.