v2.8.2
Model9 WebsiteSupportGravityFAQ
Search
⌃K
Links

Upgrading the Model9 agent

Prerequisites

  1. 1.
    The supported upgrade path is from releases 2.7.x to 2.8.x. This documentation is relevant for upgrading from releases 2.7.x only. If the installed release is older than that, refer to previous installation guides.
  2. 2.
    Verify that the agent’s installation prerequisites are met, see Prerequisites for details.

Java version

Verify that the z/OS Java is version 8 64-bit SR6 FP25 or above. Using an older Java version would result in an agent startup failure with ZM91005E message code.
Note: z/OS Java version 11 is not supported
Verify the Java version and change the Java installation directory using the following commands:
cd /usr/lpp/java/J8.0_64/bin
./java -version
java version "1.8.0_281"
Java(TM) SE Runtime Environment (build 8.0.6.25 - pmz6480sr6fp25-20210115_01(SR6 FP25))
IBM J9 VM (build 2.9, JRE 1.8.0 z/OS s390x-64-Bit Compressed References 20201218_462060 (JIT enabled, AOT enabled)
OpenJ9 - 4c03b71
OMR - 86a8e1a
IBM - 8c30c56)
JCL - 20210108_01 based on Oracle jdk8u281-b09
Note
Ensure that there are no policies scheduled to run during the upgrade operation.

Step 1: Upload the agent TAR File to the installation directory

Use FTP or a similar utility to upload the Model9 agent’s installation tar file to the Model9 agent’s installation directory. Use Passive Mode if supported by the FTP client. The tar file must be uploaded in binary mode, as shown in the following example:
$ ftp mf-lp1
Connected to mf-lp1.
220-FTPD1 IBM FTP CS V2R2 at mf-lp1, 06:20:40 on 2017-02-23.
220 Connection will not timeout.
Name (mf-lp1:m9user): m9u
331 Send password please.
Password:
230 M9U is logged on. Working directory is "M9U.".
Remote system type is MVS.
ftp> cd /usr/lpp/model9/
250 HFS directory /usr/lpp/model9/ is the current working directory
ftp> bin
200 Representation type is Image
ftp> put model9-v2.8.2_build_ebcddfb-agent.tar
local: model9-v2.8.2_build_ebcddfb-agent.tar remote:model9-v2.8.2_build_ebcddfb-agent.tar
229 Entering Extended Passive Mode (|||1026|)
125 Storing data set /usr/lpp/model9/model9-v2.8.2_build_ebcddfb-agent.tar
250 Transfer completed successfully.
xxxxxx bytes sent in 00:02 (1.95 MiB/s)
ftp> quit
221 Quit command received. Goodbye.

Step 2: 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:
su
cd /usr/lpp/model9/
tar -xpf model9-v2.8.2_build_ebcddfb-agent.tar
rm agent
ln -s model9-v2.8.2_build_ebcddfb-agent agent

Step 3: Copy the Model9 libraries from USS to PDS and modify

Edit and submit the JCL CPY#PDS located in /usr/lpp/model9/agent/installation to create the Model9 LOADLIB, SAMPLIB, and EXEC PDS files.
After the successful completion of CPY#PDS, update the following SAMPLIB PDS members:
Modify M9AGENT:
Update
Description
DD STEPLIB
Model9 installation LOADLIB
PWD environment variable
Model9 agent’s installation path
Optional parameters for M9AGENT:
Update
Description
CONF_HOME environment variable
Model9 agent’s configuration directory path
Use the CONF_HOME parameter for activating more than one agent in the same LPAR. The parameter will allow the agents to use the same Model9 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 Model9 complex. However, additional agents in the same LPAR may be required if:
  • Using a sub-plex
  • Running both development and production environments
  • 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:
//STDENV DD *
export PWD=/usr/lpp/model9/agent
export CONF_HOME=$PWD/../conf
export ENV=agent
. $PWD/scripts/stdenv-main.sh
//
Modify M9SAPI:
Update
Description
M9PATH
Model9 agent’s installation path
Modify M9LIFECY:
Update
Description
DD STEPLIB
Model9 installation LOADLIB
PWD environment variable
Model9 agent’s installation path
Copy M9AGENT, M9SAPI, M9LIFECY to your local libraries and reapply site modifications.

Step 4: Upgrade the Model9 Command Line Interface

Customize the M9CLI Rexx in the EXEC PDS to match installation standards:
fifodir = "/usr/lpp/model9/listener"
loaddir = "SYS2.MODEL9.V282.LOADLIB"
Copy the M9CLI EXEC to a site standard local EXEC library concatenated in the logon procedure.

Optional: Obfuscate the object storage credentials

Model9 allows obfuscating the object storage secret key so it won't appear 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:
objstore.endpoint.password_encrypted: true

Optional: Using the TRUSTED attribute

All Model9 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:
  • Remove OPERATIONS attribute from M9USER:
ALTUSER M9USER NOOPERATIONS
  • 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
  • Alter the M9LIFECY sample JCL to function as a Started Task (STC) by changing the JOB card to start with the following:
//M9LIFECY PROC
Note
The life Cycle job is changed into an STC and additional permission has to define for the resulting STC.

Step 5: Update the Model9 agent configuration

If upgrading from a release prior to 2.6.x 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 Model9 agent​

Step 6: Upgrade automatic recall

  1. 1.
    Use the sample JCL M9UNHOOK to uninstall the previous intercept. The expected RC should be 0:
    S M9UNHOOK
    If another intercept was installed on top of the Model9 intercept, the uninstall process finishes with RC=4. In this case, the Model9 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. It is also possible to remove the top intercept and then remove the Model9 intercept again.
  2. 2.
    Replace the previously installed release and update the PROGxx configuration by adding the following statements:
    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)
    1. 1.
      Replace<VOLSER> with the relevant volume name.
    2. 2.
      Use the SET PROG=XX operator command to apply the changes.
    3. 3.
      Verify that the command has ended successfully.
    4. 4.
      The intercept and exit must be loaded to the Dynamic LPA in order for them to function correctly. Do not use MLPA or PLPA to load the modules.
  3. 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 should be 0:
    S M9HOOK
  4. 4.
    If you are using another data management product together with Model9 Cloud Data Manager, add the following DD statement to the other product procedure to avoid collisions:
    //ZM9$NORC DD DUMMY
  5. 5.
    Restart the address space after applying the DD.

Step 7: Stop the previous agent

Stop the previous release agent:
P M9AGENT

Optional: Upgrade cloud data sets

For users who already started using Model9 Cloud Data Sets (CDS), follow the procedure below to upgrade the CDS feature.

Stopping and Uninstalling previous CDS

Continue only after the M9AGENT STC has stopped.

Vary offline

Vary offline the CDS virtual devices:
V xxxx-yyyy,OFFLINE
Make sure all devices are OFFLINE:
D U,,,xxxx,nn
For 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

Stop VDEV Started task

P M9VDEV
If "vary offline" step did not complete successfully, the VDEV started task won't shutdown.

Uninstalling CDS

Edit M9UNICDS (SAMPLIB) according to instructions and Run CDS uninstall:
Make sure you are using the M9UNICDS from the currently running version
S M9UNICDS

Remove exits

Remove OCE exit definitions using 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

Upgrading CDS

Update CDS exit modules

Update CDS exit modules in LPA using SETPROG:
SETPROG LPA,ADD,MOD=ZM9019CW,DSN=SYS2.MODEL9.V282.LOADLIB
SETPROG LPA,ADD,MOD=ZM9019CC,DSN=SYS2.MODEL9.V282.LOADLIB
SETPROG LPA,ADD,MOD=ZM9OCEX4,DSN=SYS2.MODEL9.V282.LOADLIB
Member PROGxx should have the same statements (without the SETPROG verb). Make sure they are referencing the correct data set version.

Add OCE exits

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)

Run CDS installation

Edit M9INSCDS according to the instructions of the new SAMPLIP and run CDS install:
S M9INSCDS

Edit and Start VDEV started task

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 (e.g. MA)
S M9VDEV

Vary Online

Vary online the virtual device range:
V xxxx-yyyy,ONLINE
Make sure all devices are online:
D U,,,xxxx,nn
Output for 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
Vary the Model9 library online:
V SMS,LIB(M9MTL),ONLINE

Update the enabled application list

Edit the agent.yml parameters that control the enabled applications for cloud data set.
The new default values should be set as below:
cloud_datasets.supported_read_utility_name_pattern: "(IEBGENR)|(IEBGENER)|(DSNUTILB)|(IEBCOPY)|(IDCAMS)"
.cloud_datasets.supported_write_utility_name_pattern: "(IEBGENR)|(IEBGENER)|(DSNUTILB)|(IEBCOPY)|(IDCAMS)"

Step 8: Define the Model9 loadlib as program-controlled

If you are using the PROGRAM class, define the Model9 loadlib as program controlled.
# Only if class PROGRAM is active
RALT PROGRAM * ADDMEM('SYS2.MODEL9.V282.LOADLIB'//NOPADCHK)
PERMIT * CLASS(PROGRAM) ID(M9USER) ACC(READ)
SETR WHEN(PROGRAM) REFRESH

Step 9: Start the agent

2. Start the upgraded agent using the following command:
S M9AGENT
3. 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
Previous
Upgrade the Model9 management server on zCX
Next
Installing in production
Last modified 2mo ago