Configuring the CMCI JVM server for the CICS bundle deployment API

The CICS® management client interface (CMCI) supports deploying CICS bundles into a region through the CICS bundle deployment API. This API can be used by HTTP clients, including a Gradle or Maven plug-in. To use the CICS bundle deployment API, system programmers must perform additional configuration for the CMCI JVM server.

1. Enable the CICS bundle deployment API by specifying the bundles directory (-Dcom.ibm.cics.jvmserver.cmci.bundles.dir) in your JVM profile of the CMCI JVM server, that is, EYUCMCIJ.jvmprofile for a CICSplex or EYUSMSSJ.jvmprofile for a single CICS region.
   Add the following line:

   -Dcom.ibm.cics.jvmserver.cmci.bundles.dir=<bundles_directory>

   Tips: It's recommended that you create a directory on zFS dedicated for the use of the API in managing bundles. If you are configuring the API for multiple single CICS regions (SMSS), you are also advised to create a separate dedicated bundles directory for each of them. Bundles pushed to the CICS bundle deployment API are stored in the bundles directory and accessed by the CICS target region.
2. Optional: In the JVM profile, you can also add specifications about the data that's allowed to pass the API.

   -Dcom.ibm.cics.jvmserver.cmci.deploy.timeout={120000|timeout_limit}

   Specifies the timeout limit for deploying a CICS bundle, in milliseconds. This includes the time for all bundle lifecycle actions, including disable, discard, install and enable.

   The default value is 120000 (120 seconds).

   -Dcom.ibm.cics.jvmserver.cmci.max.file.size={52428800|max_file_size}

   Specifies the maximum size allowed for the uploaded CICS bundle, in bytes. The default size is 52428800 (50 MB).

   If the size of any uploaded bundle is greater than this size, you'll receive a 400 Bad Request message SRVE8021E: The file being uploaded is too large.

   -Dcom.ibm.cics.jvmserver.cmci.max.request.size={104857600|max_request_size}

   Specifies the maximum size allowed for a multipart or form-data request, in bytes. The default size is 104857600 (100 MB).

   The web container will throw an exception if the overall size of all uploaded files exceeds this threshold.

3. Configure security levels in the CLIST.

   If you're using RACF®, you can copy and update the sample CLIST in SEYUSAMP. Use the EYU$BUND sample for CICSPlex SM or EYU$BNDS for SMSS.

   Specify the following required options:

   Table 1. Required CLIST options for CICS bundle deployment API setup

   Required options	Description	Applicable to CICSPlex SM (EYU$BUND)	Applicable to single CICS regions (EYU$BNDS)
   deploy_userid	The user ID with permission to deploy the bundle. You are recommended to create a functional ID (for example, DPLYUSR) for this purpose. Alternatively, make sure your region user ID has sufficient permissions and specify it in place of the functional ID.	✓	✓
   mngdbndl_access_list	The user groups that have access to the CICS bundle deployment API, for example, DEVELOPER.	✓	✓
   profile_prefix	The SAF profile prefix of the regions that contain the CMCI JVM server, as defined in your JVM profiles.	✓	✓
   region_userid	The user ID of the single CICS region that is configured with the CMCI JVM server.	NA	✓
   wui_region_userid	The user ID of the CICSPlex SM WUI region that is configured with the CMCI JVM server, for example, CICSRGN.	✓	NA
   cmas	The CMAS that deploy_userid, usually the deployment functional ID, is authorized to query.	✓	NA
   cicsplex	The CICSplex that deploy_userid, usually the deployment functional ID, is authorized to query and deploy bundles to.	✓	NA
   region	The target CICS region that deploy_userid, usually the deployment functional ID, is authorized to query and deploy bundles to in the specified CICSplex.	✓	NA

   The following options are optional. If not specified, the default value is used.

   Table 2. Optional CLIST options for CICS bundle deployment API setup

   Optional options	Description	Applicable to CICSPlex SM (EYU$BUND)	Applicable to single CICS regions (EYU$BNDS)
   command_class	The name of the RACF command grouping class. The default value is VCICSCMD.	NA	✓
   resource_class	The name of the RACF resource grouping class. The default value is WCICSRES.	NA	✓
   transaction_class	The name of the RACF transaction grouping class. The default value is GCICSTRN.	✓	✓
   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.	✓	✓

   Then run the CLIST.
4. Give user IDs access to the bundles directory on zFS using the UNIX command chmod or by applying access control lists (ACLs). For more information, see Implementing security for z/OS UNIX files and Giving CICS regions access to z/OS UNIX directories and files.
   • The user ID specified on the deploy_userid CLIST option (usually the deployment functional ID) needs READ, WRITE, and EXECUTE access to the bundles directory.
   • The target CICS region's region user ID needs READ and EXECUTE access to the directory.