Setting up CMCI in a single CICS region

To manage a CICS® region that is not part of any CICSplex by an HTTP client, you must set up the CICS management client interface (CMCI) in this region to turn it into a CICS System Management Single Server (SMSS). You can either configure the basic CMCI or the CMCI JVM server.

The CMCI JVM server is a Liberty server that supports the CMCI REST API, enhanced client authentication, the CMCI GraphQL API, and the CICS bundle deployment API.

Note: This configuration procedure uses the CMCI JVM server to configure the CMCI in a single CICS region. If you don't want the CMCI JVM server, you can set up the basic CMCI by following instructions in Setting up CMCI in a single CICS region in the CICS TS 5.5 product information.

These instructions cover how to install the CMCI JVM server in a single CICS region, including how to remove any existing basic CMCI configuration, if any. The CMCI JVM server (EYUCMCIJ) is automatically created in an SMSS region by setting the CPSMCONN system initialization parameter to SMSSJ. Resources required by the CMCI JVM server are automatically created, and the server is automatically configured. You then add a DD statement to the region for the EYUSMSS data set to initialize it. A sample JVM profile (EYUSMSSJ.jvmprofile) is also provided for configuring the CMCI JVM server further.

Before you begin

Planning for CMCI setup
  1. To use enhanced client authentication in the CMCI such as multifactor authentication (MFA), the CMCI GraphQL API, or the CICS bundle deployment API (extra configuration needed), you must use the CMCI JVM server with the CMCI.
  2. The CMCI JVM server must be dedicated to hosting the CMCI. Do not use the CMCI JVM server to host other applications. Because a CICS region can host multiple JVM servers, use a separate JVM server to run applications.
  3. Estimate storage requirements for the CMCI.

    You can use the following values as an initial estimate for 24-bit and 31-bit storage:

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

    This is because the supplied JVM profile 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. As the workload changes, for example, if you change the number of threads, you need to recalculate the storage requirements as described in Calculating storage requirements for JVM servers.

    For 64-bit storage, calculate their requirements as described in Estimating storage requirements for CMCI.

System requirements for the CMCI JVM server
  1. Your CICS region must be at CICS TS 5.6 with APAR PH35122, or a later release.
  2. Verify that all of the required Java™ components are installed. You can follow the Java components checklist.
  3. You must have set up Java support in CICS. That is, you have also set the JVM profile location and grant the CICS region required access. 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.
Additional requirements for enabling CICS bundle deployment API
For the minimum CICS TS version required for the region to be configured with the API, see Software requirements at Configuring the CMCI JVM server for the CICS bundle deployment API.
Additional requirements for advanced capabilities in CICS Explorer®
For the region version requirements for the aggregation function, the Map view, and sign-on with MFA credentials in CICS Explorer, see Configuring for CICS Explorer.

Procedure

If your region is not configured with any CMCI yet, skip to Step 2.

  1. If your CICS region is already configured with the basic CMCI, remove the TCPIPSERVICE and URIMAP resources that you installed when configuring the basic CMCI, and ensure that they are not reinstalled at CICS restart. For example, you can remove them from any group list that is autoinstalled at CICS startup.

    This is to avoid conflicts with the resources required by the CMCI JVM server. If the region starts with previous resources installed and the CMCI JVM server configured, EYUNX0110W or EYUNX0013E is issued.

  2. Review or change your CICS startup JCL:
    1. Ensure the hlq.CPSM.SEYUAUTH library is added to the STEPLIB concatenation, where hlq is your high-level qualifier; for example CICSTS61
    2. Ensure the hlq.CPSM.SEYULOAD library is added to the DFHRPL concatenation, where hlq is your high-level qualifier; for example CICSTS61
    These libraries must be at the same CICS TS level as those for CICS; that is, the same as the CICS hlq.CICS.SDFHAUTH and hlq.CICS.SDFHLOAD libraries in the STEPLIB concatenation.
  3. Specify storage limits on the following parameters, according to the estimate you get from Step 3 of Before you begin.
    Parameters Storage affected
    EDSALIM system initialization parameter
    31-bit (above 16 MB, above-the-line) storage
    z/OS MEMLIMIT parameter 64-bit (above-the-bar) storage
    z/OS REGION parameter
    24-bit storage (below 16 MB, below-the-line)
    31-bit storage
  4. Add the following system initialization parameters to the region:
    SIT parameters Description
    CPSMCONN=SMSSJ Automatically creates a Liberty JVM server named EYUCMCIJ, which will run the CMCI JVM server.
    Other system initialization parameters in the Mapping between region SIT parameters and CMCI JVM server configuration elements table The CMCI JVM server is autoconfigured using the values of these mapped system initialization parameters.

    Review and update these parameters as needed. For example, if you need to enable authentication for the CMCI, you need to set SEC to YES to enable Liberty security for the CMCI JVM server.

  5. Specify CMCI options and TCP/IP options to enable the CMCI in the region.
    Add a DD statement to the region for the EYUSMSS data set. For detailed instructions, see Specifying CMCI and TCP/IP options for the SMSS.
    Some option parameters such as CMCIPORT are mandatory. For more information on these options and how they are mapped to the CMCI JVM server configuration elements, see the Mapping between TCP/IP options and configuration elements in server.xml table.

Configuring the CMCI JVM server and its security

  1. Create the JVM profile for the CMCI JVM server.
    1. Copy EYUSMSSJ.jvmprofile from its installation location to the location that is specified on the JVMPROFILEDIR parameter for customization. If you haven't set JVMPROFILEDIR, see Setting the location for the JVM profiles.
      The installation location is controlled by the root directory specified on USSHOME. The default installation location is /usr/lpp/cicsts/cicsts61/JVMProfiles.
    2. Validate or update the values of the JAVA_HOME and WORK_DIR options in the JVM profile.
      For detailed description or requirements of each option, see JVM server profile options.
    3. Verify that -Dcom.ibm.ws.zos.core.angelRequired=true and -Dcom.ibm.ws.zos.core.angelRequiredServices=SAFCRED,PRODMGR,ZOSAIO have been set in EYUSMSSJ.jvmprofile.
    4. Ensure that RACF profiles BBG.AUTHMOD.BBGZSAFM.SAFCRED, BBG.AUTHMOD.BBGZSAFM.PRODMGR and BBG.AUTHMOD.BBGZSAFM.ZOSAIO in class SERVER have been created and that the CICS region user ID has been granted READ access to those profiles. See Enabling z/OS authorized services on Liberty for z/OS.
    5. If you want a selection of regions that contain CMCI JVM servers to share security configurations, specify the same SAF profile prefix for these regions.
      Note: The SAF profile prefix is used by SAF authorization to determine which RACF rules the CICS region uses. SAF authorization is automatically enabled for the CMCI JVM server.

      For example, when authenticating users for the CICS bundle deployment API, CMCI JVM servers in the CICS regions with the same SAF profile prefix allow the same users to access the API.

      For the CMCI JVM server, the SAF profile prefix defaults to the APPLID of the region. To override it, add the following line to the JVM profile:

      -Dcom.ibm.cics.jvmserver.wlp.saf.profilePrefix=${MYPREFIX}
      where ${MYPREFIX} specifies the SAF profile prefix for the CICS regions that need to share security configurations.
  2. The CMCI JVM server enables SAF authorization by default. You then need to configure a Liberty angel process to use the z/OS authorized services, including SAF.
    Create a Liberty angel if you don't have one, or use an existing Liberty angel. You can use either the default Liberty angel or a named angel provided that the version of Liberty for the angel process is the same as or higher than the version of Liberty that's running in CICS. If the default one doesn't match that criterion, either update it or use a named angel that does. For instructions on how to configure a Liberty angel process, identify the Liberty version of an existing angel, or specify a named angel, see The Liberty server angel process.
  3. Permit the user ID of the region that contains the CMCI JVM server 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 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 region that contains the CMCI JVM server 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.

  4. Tasks starting from the CMCI JVM server that are not classified as web requests run under the CJSU transaction by default. If transaction security is active in the region that contains the CMCI JVM server, give the CICS default user ID 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 to override the default user ID.
    • Or, use a duplicate transaction of CJSU for unclassified work that is run in a JVM server. You must specify the transaction ID in the com.ibm.cics.jvmserver.unclassified.tranid property to override the default transaction ID (CJSU), and give required access to this transaction.

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

  5. 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 must define the RACF EJBROLE profile &PROFILE_PREFIX.CMCI.CMCIUSER and give all CMCI users read access to this profile. To do so, you can update the sample CLIST EYU$CMCI in SEYUSAMP, 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 region that contains the CMCI JVM server runs.
      WUI_APPLID
      Specify the APPLID of the region that contains the CMCI JVM server.
      CMCIUSER_ACCESS_LIST
      Specify the list of users or groups of users that will access the CMCI through CICS Explorer.
      PROFILE_PREFIX
      Specify the prefix for SAF profiles in the EJBROLE class. By default, it's the APPLID of the region that contains the CMCI JVM server. If you specified a SAF profile prefix on the com.ibm.cics.jvmserver.wlp.saf.profilePrefix property in the JVM profile in Step 6.e. You can override the default value by setting PROFILE_PREFIX to the value specified on com.ibm.cics.jvmserver.wlp.saf.profilePrefix.
    3. Optionally, you can overwrite default values on the following options if needed:
      NOTIFY
      The TSO user ID to be notified in case of access violations. The default value is IBMUSER.
      OWNER
      The TSO user ID of the profile owner. The default value is IBMUSER.
      PROGRAM_CLASS
      The name of the RACF program grouping class. The default value is NCICSPPT.
    4. 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 in a CICSplex.

If you want to deploy CICS bundles through the CICS bundle deployment API, you must perform additional configurations for the CMCI JVM server. For instructions, see Configuring the CMCI JVM server for the CICS bundle deployment API.