Configuring CMCI in a WUI region

If a WUI region does not have the CMCI, you can set up the CMCI in this WUI region. This procedure assumes that you will use the CMCI JVM server with the CMCI. The CMCI JVM server is a Liberty server that provides support for enhanced client authentication in the CMCI and support for the GraphQL API.

If you opt not to use the CMCI JVM server, follow the instructions in Setting up CMCI with CICSPlex SM in the CICS TS 5.4 product information.

Before you begin

System requirements for the CMCI JVM server
  1. Verify that all of the required Java components are installed. You can follow the Java components checklist.
  2. Ensure that Java support is set up in the region. For instructions, see Setting up Java support.
Additional requirements for enabling connections with multi-factor authentication (MFA) credentials
  • You must have IBM® Multi-Factor Authentication for z/OS® or an equivalent product configured with RACF to support multi-factor authentication. If you use an alternative external security manager (ESM), refer to your vendor for details.
  • MFA is supported by CICS TS V5.4 with APAR PI87691 or later. Ensure that the region where the CMCI JVM server will be running, and the CMAS to which it connects are at the same CICS level that is CICS TS V5.4 with APAR PI87691 or later. For information about CICS level considerations for setting up your CICSPlex® SM topology, see Designing your CICSPlex SM environment.
Additional requirements for the GraphQL API feature
  • The region is at CICS® TS 5.5 or later.

Procedure

  1. Specify appropriate levels of 64-bit (above-the-bar) storage in the region, and auxiliary storage, as follows:
    • Use the z/OS MEMLIMIT parameter to set the limit for 64-bit storage in the region
    • Use the MAXAUXCPSM and MAXAUXTOTL CICSPlex SM system parameters, to set auxiliary storage for the CMAS.

    See Estimating storage requirements for CMCI for guidance about setting these values to avoid possible storage problems.

  2. Ensure that the CICS system initialization parameter CSDSTRNO is at least four (CSDSTRNO=4) so that CICS Explorer® can inquire on CICS resources on the CSD, for example, programs, files, or transactions.

    If CSDSTRNO is lower than four, the request might fail with CNX0591E RESP=CSDERR RESP2=5 (insufficient VSAM strings).

  3. Review the values of KEYRING, NISTSP800131A, and SEC system initialization parameters.
    These system initialization parameters, together with APPLID and DFLTUSER, are mapped to the CMCI JVM server configuration parameters. Be aware that in some cases, additional configuration might be required in the CMCI JVM server. For more information, see Configuration parameter mapping between CICSPlex SM WUI server and CMCI JVM server.
  4. Specify WUI server initialization parameters to enable the use of the CMCI with CICSPlex SM.
    These parameters include CMCI options, TCP/IP options, environment options, and so on.
    When you specify the WUI server initialization parameters, consider the following issues:
    • You must specify a unique value for the CMCIPORT parameter. This parameter allocates a TCP/IP port number to the CMCI. Setting a value for the CMCIPORT parameter ensures that the CMCI is installed on the WUI region. The CMCI must use a different port to the Web User Interface.
    • By default, URIMAP, and TCPIPSERVICE resource definitions are autoinstalled with security settings derived from the SEC CICS system initialization parameter and the TCPIPSSL WUI server initialization parameter. You can override the default CMCI TCPIPSERVICE settings by using the optional CMCIAUTH and CMCISSL parameters to enable SSL certification for greater security. See CICSPlex SM Web User Interface security access overview for more information about setting up security for the WUI.
    • Consider setting a nonzero value for the DEFAULTWARNCNT WUI server initialization parameter. Setting an appropriate value for this parameter prevents the retrieval of unacceptable amounts of data and can avoid long waits and potential storage problems when making requests on CICS resources. See Record count warnings in CMCI for guidance about the warning count mechanism in the CMCI.

    For detailed instructions, see Web User Interface server initialization parameters.

    Note: It is helpful to know how the WUI server initialization parameters such as the CMCI options and TCP/IP options are mapped to the CMCI JVM server configuration parameters. Be aware that some values are not compatible with the CMCI JVM server. For more information, see Configuration parameter mapping between CICSPlex SM WUI server and CMCI JVM server.
  5. Ensure that resource definition group DFHWU is installed.
    Group DFHWU contains the resource definitions that are required for a CMCI environment.

Configuring the CMCI JVM server

  1. Add the following system initialization parameters to the region:
  2. Create the JVM profile for the CMCI JVM server.
    1. Copy EYUCMCIJ.jvmprofile from /usr/lpp/cicsts/cicsts55/JVMProfiles to the location that is specified in the JVMPROFILEDIR system initialization parameter.
    2. Validate or update the values of JAVA_HOME and WORK_DIR in the JVM profile.
      For details, see Symbols used in the JVM profile.
  3. Establish the storage requirements for the CMCI JVM server.

    The supplied EYUCMCIJ.jvmprofile file disables the use of the shared library region, which reduces the amount of non-CICS 31-bit storage required. By default, the JVMSERVER resource that is automatically created for the CMCI JVM server has a value of 15 for the THREADLIMIT attribute. Therefore, you can use the following values as an initial estimate for storage requirements:

    • 24-bit storage: 512 KB
    • 31-bit storage: 100 MB

    Continue to monitor and review storage requirements as described in Calculating storage requirements for JVM servers.

  4. Configure the Liberty angel process started task for the CMCI JVM server.
    1. If you don't have a Liberty angel process running, follow the steps in The Liberty server angel process to create one.
    2. If you already have a Liberty angel process running, ensure the version of Liberty specified in the ROOT symbolic parameter in the angel JCL is at the same or a higher level to the version of Liberty supplied with CICS.
      Example: Identifying the Liberty version from the started task system log

      If the Liberty angel process is running Liberty 18.0.0.2 or above, the started task system log contains a message that indicates the Liberty version:

      CWWKB0079I THE ANGEL BUILD LEVEL IS 18.0.0.2 20180619-0654 2018.7.0.0 20180619-0654
      Example: Identifying the Liberty version from message DFHSJ1405

      The version of a Liberty running in a CICS JVM server is available in the following message:

      DFHSJ1405I 08/22/2018 17:04:39 IYK3ZDRI JVMSERVER EYUCMCIJ is running WebSphere Application Server 
                            Version 18.0.0.2 Liberty - (18.0.0.2-cl180220180619-0403) process ID 67174497.
      Example: Identifying the Liberty version by running scripts
      Suppose that the angel JCL specifies the following ROOT parameter:
      
// SET ROOT='/usr/lpp/zosmf/wlp'
      To find out what the version of Liberty is, run the following script:
      
/usr/lpp/zosmf/wlp/bin/productInfo version --verbose
      For CICS, run the following script:
      /usr/lpp/cicsts55/wlp/bin/productInfo version --verbose
      Figure 1. Example output
      
WebSphereApplicationServer.properties:
        com.ibm.websphere.productId=com.ibm.websphere.appserver
        com.ibm.websphere.productOwner=IBM
        com.ibm.websphere.productVersion=16.0.0.3
        com.ibm.websphere.productName=WebSphere Application Server
        com.ibm.websphere.productInstallType=Archive
        com.ibm.websphere.productEdition=zOS
        com.ibm.websphere.productLicenseType=IPLA

WebSphereApplicationServerZOS.properties:
        com.ibm.websphere.productId=com.ibm.websphere.appserver.zos
        com.ibm.websphere.productOwner=IBM CORP
        com.ibm.websphere.productVersion=16.0.0.3             <== Liberty Version    
        com.ibm.websphere.productName=WAS FOR Z/OS
        com.ibm.websphere.productPID=5655-WAS
        com.ibm.websphere.productQualifier=WAS Z/OS
        com.ibm.websphere.productReplaces=com.ibm.websphere.appserver
        com.ibm.websphere.productEdition=
        com.ibm.websphere.gssp=true

zOSMF.properties:
        com.ibm.websphere.productId=com.ibm.zoszmf
        com.ibm.websphere.productOwner=IBM
        com.ibm.websphere.productVersion=2.2.0
        com.ibm.websphere.productName=z/OSMF
        com.ibm.websphere.productPID=5650-ZOS
        com.ibm.websphere.productQualifier=z/OSMF
        com.ibm.websphere.productReplaces=com.ibm.websphere.appserver.zos
        com.ibm.websphere.productEdition=N/A
    3. If the version of Liberty is at a lower level to the version of Liberty supplied with CICS, configure a named angel process using the CICS Liberty install:
      1. Uncomment the following line in the JVM profile for the CMCI JVM server, EYUCMCIJ.jvmprofile:
        
#-Dcom.ibm.ws.zos.core.angelName=<named_angel>
      2. Specify the angel name in the -Dcom.ibm.ws.zos.core.angelName property.

        This property enables the CMCI JVM server to connect to the named angel process. For details, see The Liberty server angel process.

    4. Ensure that the Liberty angel process is ready before starting the region.
  5. Configure security for the WUI region to use the Liberty angel process.

    If you are using RACF, you can use the sample CLIST EYU$ANGL in SEYUSAMP to create RACF definitions for the WUI region to use the Liberty angel process, as follows:

    1. Take a copy of the CLIST EYU$ANGL in SEYUSAMP.
    2. Update the copy by specifying the following variables:
      WUI_REGION_USERID
      Specify the user ID under which the WUI region runs.
      ANGEL_NAME
      If you are using a named angel process, the value is ANGEL.name where name is the value of the -Dcom.ibm.ws.zos.core.angelName property.

      If you are not using a name angel process (-Dcom.ibm.ws.zos.core.angelName is not specified), the value is ANGEL.

    3. Run the CLIST.

    If you are using an external security manager other than RACF, refer to the documentation of the external product for instructions.

  6. Tasks that emanate from the CMCI JVM server run under the CJSU transaction by default. If transaction security is active in the WUI region, give the CICS default user access to the CJSU transaction.

    Alternatively, you can create a new user ID based on the CICS default user, with additional access to the CJSU transaction. You must specify the user ID in the com.ibm.cics.jvmserver.unclassified.userid property.

    You can also use a duplicate transaction of CJSU for unclassified work that is run in a JVM server. In this case, you must specify the transaction ID in the com.ibm.cics.jvmserver.unclassified.tranid property, and give required access to this transaction.

    For more information about JVM system properties, see JVM system properties.

    For more information about Liberty JVM server security configuration, see Configuring security for a Liberty JVM server.

  7. Update the region JCL to include new DD statements for CMCI diagnostics. 
    
//JVMOUT   DD SYSOUT=*,LRECL=1024
//JVMERR   DD SYSOUT=*,LRECL=1024
//JVMTRACE DD SYSOUT=*,LRECL=1024
//MSGLOG   DD SYSOUT=*,LRECL=1024
  8. Set the following feature toggle to enable the use of the CMCI JVM server. 
    com.ibm.cics.cmci.jvmserver=true

    For detailed instructions, see Specifying feature toggles.

  9. Enable users to authenticate through the CMCI JVM server.
    You must give users access to authenticate with the CMCI JVM server, including the authority to use the CMCI.

    If you are using RACF, you can use the sample CLIST EYU$CMCI in SEYUSAMP to create RACF definitions for users to authenticate through the CMCI JVM server, as follows:

    1. Take a copy of the CLIST EYU$CMCI in SEYUSAMP.
    2. Update the copy by specifying the following variables:
      WUI_REGION_USERID
      Specify the user ID under which the WUI region runs.
      WUI_APPLID
      Specify the APPLID of the WUI region.
      CMCIUSER_ACCESS_LIST
      Specify the list of users or groups of users that will access the CMCI through CICS Explorer.
    3. Run the CLIST.

    If you are using an external security manager other than RACF, refer to the documentation of the external product for instructions.

What to do next

If you want to limit clients that can connect to the CMCI JVM server, you can define a client allowlist to the CMCI JVM server. For instructions, see Defining a client allowlist to CMCI JVM server.