Upgrading the BMC AMI Cloud agent

Before you begin

Verify that the agent’s installation prerequisites are met. For more information, see z-OS-agent-requirements.

Verify that the z/OS Java is version 8 64-bit SR6 FP25 or later. Using an earlier Java version would result in an agent startup failure with message number ZM91005E.

Verify the Java version and change the Java installation directory by using the following commands:

Task 1: To obtain the installation files and license key

Skip this task if you have already downloaded the installation files and obtained a license key as explained in Upgrading-the-management-server-on-Linux or Upgrading-the-management-server-on-zCX.

1. Go toElectronic Product Distribution (EPD) and log in.

2. Using the search bar, search for either BMC AMI Cloud Data or BMC AMI Cloud Vault. Both product files are composed with the same binaries.
3. Click the version that you want to download. 
4. On the Product tab, select the files and click Download.
5. Select the License Information tab to download a temporary license key.

6. To obtain a full license key, go toSupport Central and select Case Management. 

7. Open a license key request by clicking on Create New Case and filling in the required information. 

   Important

   The output of the z/OS command D M=CPU is required.

Task 2: To upload the agent TAR file to the installation directory

Use FTP or a similar utility to upload the BMC AMI Cloud agent’s installation tar file to the BMC AMI Cloud agent’s installation directory. Use Passive Mode if it's supported by the FTP client. The tar file must be uploaded in binary mode, as shown in the following example:

Task 3: To upgrade the agent binaries

In OMVS, extract the tar file and replace the agent symbolic link with a reference to the new directory, as shown in the following example:

Task 4: To copy the BMC AMI Cloud libraries from USS to PDS and modify

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.

After the successful completion of CPY#PDS, update the following SAMPLIB PDS members:

Modify M9AGENT:

Optional parameters for M9AGENT:

Use the CONF_HOME parameter to activate more than one agent in the same LPAR. This parameter allows the agents to use the same BMC AMI Cloud installation files and libraries, but each will have a different configuration directory. The recommendation is to have one agent per LPAR, while all agents in the same GRS complex point to the same BMC AMI Cloud complex. However, additional agents in the same LPAR might be required if the following conditions exist:

• You are using a subplex.
• You are running both development and production environments.
• You are pointing different agents to different cloud storage.

The CONF_HOME parameter must precede the stdenv-main.sh statement. The following is an example of using the parameter:

Modify M9SAPI:

Modify M9LIFECY:

Copy M9AGENT, M9SAPI, M9LIFECY to your local libraries and reapply site modifications.

Task 5: To upgrade the BMC AMI Cloud Command Line Interface

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

Copy the M9CLI EXEC to a site standard local EXEC library concatenated in the logon procedure.

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

You can obfuscate the object storage secret key to prevent it appearing in clear text within the configuration files.

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's configuration file:

Task 7: (Optional) To use the TRUSTED attribute

All BMC AMI Cloud z/OS components can use the TRUSTED RACF attribute, instead of providing the OPERATIONS attribute to the M9USER (default user name). To replace the security setting, follow these steps:

1. Remove the OPERATIONS attribute from M9USER:

   ALTUSER M9USER NOOPERATIONS

2. Add TRUSTED attribute to all STCs:

   RALTER STARTED M9AGENT.** STDATA(USER(M9USER) GROUP(SYS1) TRUSTED(YES))
   RALTER STARTED M9HOOK.** STDATA(USER(M9USER) GROUP(SYS1) TRUSTED(YES))
   RALTER STARTED M9UNHOOK.** STDATA(USER(M9USER) GROUP(SYS1) TRUSTED(YES))
   RALTER STARTED M9VDEV.** STDATA(USER(M9USER) GROUP(SYS1) TRUSTED(YES))
   RALTER STARTED M9INSCDS.** STDATA(USER(M9USER) GROUP(SYS1) TRUSTED(YES))
   RALTER STARTED M9UNICDS.** STDATA(USER(M9USER) GROUP(SYS1) TRUSTED(YES))
   RDEFINE STARTED M9LIFECY.** STDATA(USER(M9USER) GROUP(SYS1) TRUSTED(YES))
   SETROPTS RACLIST(STARTED) REFRESH

3. Alter the M9LIFECY sample JCL to function as a Started Task (STC) by changing the JOB card to start with the following characters:

   //M9LIFECY PROC

Task 8: To update the BMC AMI Cloud agent configuration

If you are upgrading from a version earlier than 2.6.xx, and the autorecall.functionality.enabled was set within the agent.yml configuration file, the parameter name was changed to a new name to match its actual meaning. The new parameter name is xcf.functionality.enabled and its default value is true. For more details about the agent's parameters, see Installing-the-BMC-AMI-Cloud-agent.

Task 9: To upgrade automatic recall

1. Use the sample JCL M9UNHOOK to uninstall the previous intercept. The expected RC is 0:

   S M9UNHOOK

   If another intercept was installed on top of the BMC AMI Cloud intercept, the uninstall process finishes with RC=4. In this case, the BMC AMI Cloud intercept is not removed but rather logically disabled, to prevent harming the subsequent intercept. This is a valid situation that will be corrected by the next IPL. You can also remove the top intercept and then remove the BMC AMI Cloud intercept again.

2. Replace the previously installed release and update the PROGxx configuration as follows:
   

   1. Add the following statements, replacing <VOLSER> with the relevant volume name:

      APF ADD DSNAME(SYS2.MODEL9.V282.LOADLIB) VOLUME(<VOLSER>)
      LPA ADD DSNAME(SYS2.MODEL9.V282.LOADLIB) MOD(ZM9CPTN)
      LPA ADD DSNAME(SYS2.MODEL9.V282.LOADLIB) MOD(ZM9S26X)
   2. Use the SET PROG=XX operator command to apply the changes.
   3. Verify that the command has ended successfully.
   4. Load the intercept and exit modules to the Dynamic LPA. Do not use MLPA or PLPA to load the modules.

3. Install the feature by copying M9HOOK from the SAMPLIB PDS to a local PROCLIB member. Customize and activate the intercept using the following command. The expected RC is 0:

   S M9HOOK

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

   //ZM9$NORC DD DUMMY
5. After applying the DD, restart the address space.

Task 10: To stop the previous agent

Run the following command:

Task 11: (Optional) To upgrade Cloud Data Sets

If you already started using Cloud Data Sets (CDSs), perform the following procedure to upgrade the CDS feature:

1. Vary the CDS virtual devices offline:

   V xxxx-yyyy,OFFLINE

2. Make sure that all devices are OFFLINE:

   D U,,,xxxx,nn

   Example

   UNIT TYPE STATUS
   0570 348M F-NRD
   0571 348M F-NRD
   0572 348M F-NRD
   0573 348M F-NRD
   0574 348M F-NRD
   0575 348M F-NRD
   0576 348M F-NRD
   0577 348M F-NRD
   0578 348M F-NRD
   0579 348M F-NRD
   057A 348M F-NRD
   057B 348M F-NRD
   057C 348M F-NRD
   057D 348M F-NRD
   057E 348M F-NRD
   057F 348M F-NRD

3. Stop the VDEV started task by running the following command:

   P M9VDEV

   Warning

   If the vary offline step did not complete successfully, the VDEV started task won't shut down.

4. Edit M9UNICDS (SAMPLIB) according to instructions and run CDS uninstall as follows:

   Important

   Make sure that you are using the M9UNICDS from the currently running version.

   S M9UNICDS

5. Remove OCE exit definitions by using the SETPROG command:

   SETPROG EXIT,DELETE,EXITNAME=OCE_VOLUMEMOUNT,MOD=ZM9OCEX4
   SETPROG EXIT,DELETE,EXITNAME=OCE_FILESTART,MOD=ZM9OCEX4
   SETPROG EXIT,DELETE,EXITNAME=OCE_FILEEND,MOD=ZM9OCEX4
   SETPROG EXIT,DELETE,EXITNAME=OCE_FILEVALIDATE,MOD=ZM9OCEX4
   SETPROG EXIT,DELETE,EXITNAME=OCE_LABELANOMALY,MOD=ZM9OCEX4

6. Update the CDS exit modules in LPA by using SETPROG:

   SETPROG LPA,ADD,MOD=ZM9019CW,DSN=SYS2.MODEL9.V300.LOADLIB
   SETPROG LPA,ADD,MOD=ZM9019CC,DSN=SYS2.MODEL9.V300.LOADLIB
   SETPROG LPA,ADD,MOD=ZM9OCEX4,DSN=SYS2.MODEL9.V300.LOADLIB

   Important

   Member PROGxx should have the same statements (without the SETPROG verb). Make sure that they are referencing the correct data set version.

7. Add the OCE exits by running the following commands:

   SETPROG EXIT,ADD,EXITNAME=OCE_VOLUMEMOUNT,MOD=ZM9OCEX4,ABENDNUM=(100,CONSEC)
   SETPROG EXIT,ADD,EXITNAME=OCE_LABELANOMALY,MOD=ZM9OCEX4,ABENDNUM=(100,CONSEC)
   SETPROG EXIT,ADD,EXITNAME=OCE_FILEVALIDATE,MOD=ZM9OCEX4,ABENDNUM=(100,CONSEC)
   SETPROG EXIT,ADD,EXITNAME=OCE_FILEEND,MOD=ZM9OCEX4,ABENDNUM=(100,CONSEC)
   SETPROG EXIT,ADD,EXITNAME=OCE_FILESTART,MOD=ZM9OCEX4,ABENDNUM=(100,CONSEC)

8. Edit M9INSCDS according to the instructions of the new SAMPLIP and run CDS install as follows:

   S M9INSCDS

9. Edit M9VDEV according to the instructions of the new SAMPLIB and start it.
   Make sure that you change the VOLPREF parameter to the new prefix (For example, MA):

   S M9VDEV

10. Vary the virtual device range online:

    V xxxx-yyyy,ONLINE

11. Make sure that all devices are online:

    D U,,,xxxx,nn

    Example

    UNIT TYPE STATUS
    0570 348M O
    0571 348M O
    0572 348M O
    0573 348M O
    0574 348M O
    0575 348M O
    0576 348M O
    0577 348M O
    0578 348M O
    0579 348M O
    057A 348M O
    057B 348M O
    057C 348M O
    057D 348M O
    057E 348M O
    057F 348M O

12. Vary the BMC AMI Cloud library online:

    V SMS,LIB(M9MTL),ONLINE

13. Edit the agent.yml parameters that control the enabled applications for the CDS.
    The new default values should be set as follows:

    cloud_datasets.supported_read_utility_name_pattern: "(IEBGENR)|(IEBGENER)|(DSNUTILB)|(IEBCOPY)|(IDCAMS)"
    .cloud_datasets.supported_write_utility_name_pattern: "(IEBGENR)|(IEBGENER)|(DSNUTILB)|(IEBCOPY)|(IDCAMS)"

Task 12: To define the BMC AMI Cloud loadlib as program-controlled

If you are using the PROGRAM class, define the BMC AMI Cloud loadlib as program controlled:

Task 13: To start the agent

1. Start the upgraded agent by using the following command: 

   S M9AGENT

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

   ZM91002I MODEL9 BACKUP AGENT VERSION 2.8.2 INITIALIZING
   ZM91000I MODEL9 BACKUP AGENT INITIALIZED