Giving CICS regions permission to access HFS directories and files

Because your CICS regions have a z/OS UNIX user identifier (UID), and their connect group (the RACF group) has a z/OS UNIX group identifier (GID), z/OS UNIX System Services treats each CICS region as a UNIX user. There are four ways to grant a user permissions to access HFS directories and files:
To check the permissions for files and directories in a path, go to the directory where you want to start, and issue the following UNIX command:
ls -la
For example, if this command is issued in the z/OS UNIX System Services shell environment when the current directory is the home directory of CICSHT##, a list such as the following is displayed:
/u/cicsht##:>ls -la                                       
total 256                                                          
drwxr-xr-x   2 CICSHT## CICSTS31     8192 Mar 15  2004 .           
drwx------   4 CICSHT## CICSTS31     8192 Jul  4 16:14 ..          
-rw-------   1 CICSHT## CICSTS31     2976 Dec  5  2004 Snap0001.trc
-rw-r--r--   1 CICSHT## CICSTS31     1626 Jul 16 11:15 dfhjvmerr   
-rw-r--r--   1 CICSHT## CICSTS31        0 Mar 15  2004 dfhjvmin    
-rw-r--r--   1 CICSHT## CICSTS31      458 Oct  9 14:28 dfhjvmout   
-rw-r--r--   1 CICSHT## CICSTS31    64175 May 11 18:00 event.log   
/u/cicsht##:>                                            
Permissions are indicated, in three sets, by the letters r, w, x and -. These represent READ, WRITE, EXECUTE, and NONE respectively, and are shown in the left-hand column of the display, starting with the second character. The first set are the owner permissions, the second the group permissions, and the third "other" permissions. In all these examples, the owner has read and write permissions, but the group and all others have only read.
Note: The name of the file owner (CICSHT## in the example) is displayed in the list, but owner permissions are actually associated with the UID. If other CICS region user IDs have been assigned the same UID, they have the same permissions as CICSHT##. Remember that this practice is not normally recommended in a z/OS UNIX system.

You need to give each CICS region permission to access the HFS directories and files that it uses. To give your CICS regions permissions, you must be either a superuser on z/OS UNIX, or the owner of the directories and files. For directories and files supplied by CICS or by the IBM JVM, the owner is initially set as the UID of the system programmer who installs the product. Also, if you are giving CICS access using group permissions, the owner of the directories and files must be connected to the RACF group that you chose for all your CICS regions to access z/OS UNIX. The owner could have that RACF group as their default group (DLFTGRP) or be connected to it as one of their supplementary groups.

When you need to change the permissions for directories and files, use the UNIX command chmod. z/OS UNIX System Services Command Reference, SA22-7802, and z/OS UNIX System Services User's Guide, SA22-7801, has information about using this command. The following examples should help:
chmod -R g=rwx directory
    sets the group permissions for the named directory and its
    subdirectories and files to read, write and execute
    (-R applies permissions Recursively to all
    subdirectories and files)
chmod g+rx filename
    sets the group permissions for the named file to read and execute
chmod g-w filename filename
    sets the group write permission off for the two named files

u is for user (owner) permissions, g is for group permissions, 
o is for other permissions
Start of change

HFS permissions for CICS Web support

When you use HFS files to provide static responses to requests from Web clients, a CICS region which receives those requests and provides the responses needs read access to the HFS files and to the directories containing them.

If you have stored all the files relevant to each CICS region in a directory structure below the home directory for the CICS region, you can make the CICS region the owner of each directory and file (with the appropriate owner permissions). If some HFS files are used by more than one CICS region, you will need to use one of the other solutions described in this topic, such as group permissions or access control lists (ACLs). In the procedure described below for Java support, the first step gives examples of how to set up group permissions for HFS directories and files used by multiple CICS regions. The use of "other" permissions, which would give access to every HFS user, is not recommended for CICS Web support in a production environment.

End of change

HFS permissions for Java support

When you are setting up Java support in a CICS region, the required directories and files fall into three categories:
  1. The directories and files that every CICS region needs to create JVMs.
  2. The working directory that you have specified for input, output and messages from the JVMs in each individual CICS region. (This might be the home directory for the CICS region.)
  3. Any other directories and files that you have told a CICS region to use in the process of creating JVMs, or in support of CORBA applications and enterprise beans. This includes any directories and files that you have changed from their original locations, for example, JVM profiles that you have moved to a different directory. It also includes any directories and files that you have added to be used with JVMs or for CORBA applications and enterprise beans, for example, your own application classes, or classes that you have added to the trusted middleware class path.

If you want to give CICS access to the files required for Java support using group permissions, you can use the following procedure to grant the appropriate permissions. If you want to give CICS access using another type of permission, or a combination of the different permissions depending on the level of security that you require for each type of directory or file, then you can use the following procedure, but substitute an alternative type of permission ("other" or owner) as appropriate for the different types of directory or file.

  1. The directories and files that every CICS region needs to create JVMs are set up when you install CICS, and when you install the IBM® Software Developer Kit for z/OS®, Java™ 2 Technology Edition, Version 1.4.2. These directories and files are:
    • Most of the files in the /usr/lpp/cicsts/cicsts31 directory and its subdirectories. The cicsts31 directory name is a user-defined value that you chose for the CICS_DIRECTORY variable used by the DFHIJVMJ job during CICS installation; cicsts31 is the default. The files in this directory and its subdirectories include the supplied sample JVM profiles and JVM properties files, the CICS-supplied JAR files such as dfjcics.jar and dfjcsi.jar, and some of the files that CICS includes on the trusted middleware class path.
    • Some of the files in the /usr/lpp/java142/J1.4/bin and /usr/lpp/java142/J1.4/bin/classic directories that contain the IBM persistent reusable JVM code. The java142/J1.4 directory names are the default values when you install the IBM Software Developer Kit for z/OS, Java 2 Technology Edition, Version 1.4.2.
    Each CICS region requires read and execute access to these directories and files. To grant this access:
    1. Display the directories and files as described earlier in this topic, and check that the group permissions for the directories and files give the correct access to the group (the second set of permissions). If you need to change the permissions, use the UNIX command chmod, as described earlier in this topic.
    2. Assign to the RACF group that all your CICS regions can use, the group permissions for the /usr/lpp/cicsts/cicsts31 directory and its subdirectories, and for the files in them. To do this, issue the UNIX command
      chgrp -R GID /usr/lpp/cicsts/cicsts31
      where GID is the numeric z/OS UNIX group identifier (GID) which you assigned to the RACF group that all your CICS regions can use. The -R in the command means that the group is changed for not only the cicsts31 directory, but also all the subdirectories, and all the files in the directory and subdirectories. Because your CICS region user IDs are connected to this group, the CICS regions now have read and execute permission for all these directories and files.
    3. Assign to the same RACF group, the group permissions for the /usr/lpp/java142/J1.4/bin directory and its subdirectories, and the files in them. To do this, issue the UNIX command
      chgrp –R GID /usr/lpp/java142/J1.4/bin
      as you did above for the /usr/lpp/cicsts/cicsts31 directory. Your CICS regions now have read and execute permission for all these directories and files.
  2. The working directories that you have specified for input, output and messages from the JVMs in each individual CICS region are specified on the WORK_DIR option in the JVM profiles used in the CICS region, and also in any Java class that you have specified on the USEROUTPUTCLASS option to redirect stdout and stderr output from JVMs. The default working directories are as follows:
    • For the WORK_DIR option, the default working directory as specified in the supplied sample JVM profiles is the home directory of the CICS region user ID (that is, the directory /u/CICS region userid), which you should have created while following the procedure described in Giving CICS regions a z/OS UNIX user identifier (UID) and group identifier (GID) and setting up a home directory. If the CICS region user ID does not have this home directory, /tmp is used by default as the working directory.
    • For the USEROUTPUTCLASS option, if you are using the CICS-supplied sample class com.ibm.cics.server.SJMergedStream, the default working directory is the directory specified on the WORK_DIR option in the JVM profile. If you are using the alternative CICS-supplied sample class com.ibm.cics.server.SJTaskStream, the default working directories are /work_dir/applid/stdout and /work_dir/applid/stderr, where work_dir is the directory specified on the WORK_DIR option in the JVM profile, and applid is the applid of the CICS region. The USEROUTPUTCLASS option is not active in the supplied sample JVM profiles.
    If you have specified a different directory on the WORK_DIR option, or used the USEROUTPUTCLASS option to specify a Java class, in any of the JVM profiles in your CICS region, find out the names of the HFS directories that are used by the WORK_DIR option or the Java class.

    Each CICS region requires read, write and execute access to the HFS directories that you have identified as being used as a working directory or for output from JVMs in that region. If a directory is unique to a CICS region (for example, if it is based on a unique home directory that you created for the region, or if it was created using the special symbol &applid; and so includes the CICS region's unique applid), then you can make the CICS region's UID the owner of the directory and its subdirectories, and use the owner permissions to give the appropriate permissions to the CICS region. However, if more than one CICS region uses a particular directory, then you need to use group permissions so that all the CICS regions have access to the directory. For each directory that is used by more than one CICS region, follow the same procedure that you carried out for the directories and files that every CICS region needs to create JVMs, ensuring that you give the group write access (w) as well as read and execute access.

  3. Other directories and files that you have told a CICS region to use in the process of creating JVMs, or in support of CORBA applications and enterprise beans need the correct permissions applied too. If you are starting to set up JVMs in a CICS region for the first time, you probably do not have any other directories and files at this stage. You will have other directories and files if:
    • You add directory paths to the CLASSPATH option in a JVM profile or to the ibm.jvm.shareable.application.class.path system property in a JVM properties file, so that the JVM will search those directories for your own application classes.
    • You add directory paths to the TMPREFIX or TMSUFFIX options on a JVM profile, so that they will be part of the trusted middleware class path.
    • You add directory paths to the LIBPATH, which contains the directories that are searched for native C dynamic link library (DLL) files that are used by the JVM, including those required to run the JVM and additional native libraries loaded by trusted code.
    • You create your own JVM profiles or JVM properties files, or move the supplied JVM profiles or JVM properties files to a directory that is not under the /usr/lpp/cicsts/cicsts31 directory. (You can use the EXEC CICS INQUIRE JVMPROFILE command to find the HFS directory that contains a JVM profile, provided that the JVM profile has been used during the lifetime of the CICS region. The HFS directory for a JVM properties file is specified by the JVMPROPS option on the JVM profiles that reference it.)
    • You move any of the files that every CICS region needs to create JVMs, that is, the files in the /usr/lpp/cicsts/cicsts31 directory, or the /usr/lpp/java142/J1.4/bin and /usr/lpp/java142/J1.4/bin/classic directories.
    • You set up a shelf directory or a deployed JAR file directory (also known as a pickup directory) to support CORBA applications or enterprise beans.
    Each CICS region requires read and execute access to all the HFS directories and files that you have identified in this category. If you have already set up any of these items, make sure that you have set the correct permissions for the directories and files involved, and given your CICS regions permission to access them. When you set up these items later on, return to this topic and for each directory or file, follow the same procedure that you carried out for the directories and files that every CICS region needs to create JVMs.