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.
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
-
- 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.
- 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.
-
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
-
- Your CICS region must be at CICS TS 5.6
with APAR PH35122, or a later release.
- Verify that all of the required Java™ components are installed. You can follow the Java components
checklist.
- 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.
- 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.
- Review or change your CICS startup
JCL:
- Ensure the hlq.CPSM.SEYUAUTH library is added
to the STEPLIB concatenation, where hlq is your high-level qualifier; for example
CICSTS61
- 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.
- 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
|
- 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.
|
- Specify CMCI options and TCP/IP options to enable the CMCI in the region.
Configuring the CMCI JVM server
and its security
- Create the JVM profile for the CMCI JVM server.
- 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
.
- Validate or update the values of the
JAVA_HOME and WORK_DIR options in the JVM profile.
- 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.
- 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.
- 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.
- 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.
- 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:
- Take a copy of the CLIST EYU$ANGL in SEYUSAMP.
- 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
.
-
Run the CLIST.
If you are using an external security manager other than RACF, refer to the documentation of the external product for instructions.
- 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.
- 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:
- Take a copy of the CLIST EYU$CMCI in SEYUSAMP.
- 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.
- 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
.
- 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.