Upgrading the Model9 agent
- 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.
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.
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.
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
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.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.
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
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.
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- 1.Use the sample JCL M9UNHOOK to uninstall the previous intercept. The expected RC should be 0:S M9UNHOOKIf 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.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.Replace
<VOLSER>
with the relevant volume name. - 2.Use the SET PROG=XX operator command to apply the changes.
- 3.Verify that the command has ended successfully.
- 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.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.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.Restart the address space after applying the DD.
Stop the previous release agent:
P M9AGENT
For users who already started using Model9 Cloud Data Sets (CDS), follow the procedure below to upgrade the CDS feature.
Continue only after the M9AGENT STC has stopped.
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
P M9VDEV
If "vary offline" step did not complete successfully, the VDEV started task won't shutdown.
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 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
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.
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)
Edit M9INSCDS according to the instructions of the new SAMPLIP and run CDS install:
S M9INSCDS
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 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
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)"
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
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
Last modified 2mo ago