The Liberty angel process

When you include the cicsts:security-1.0 feature, the CICS Liberty JVM server uses the angel process to call z/OS® authorized services such as System Authorization Facility (SAF).

Optionally, you can name an angel process. If an angel process is not given a name, it becomes the default angel process. You can only have one default angel process. If you try to create another, it will fail to start. All the Liberty servers that are running on a z/OS image can share a single angel process. This is regardless of the level of code that the servers are running or whether they are running in a CICS® JVM server. For further information on named angel processes, see Named angel.

Important: Install the latest version of the angel process, regardless of which product it is bundled with. The latest version might be bundled with other IBM® software, and might supersede the version that is bundled with CICS.

Running the angel process started task

  1. Locate the JCL procedure for the started task in the USSHOME directory, for example: /usr/lpp/cicsts54/wlp/templates/zos/procs/bbgzangl.jcl
  2. Modify and copy the JCL procedure to a JES procedure library. You can set ROOT to the value of USSHOME/wlp, for example: ROOT=/usr/lpp/cicsts54/wlp
  3. Start the angel process. In the following examples, [.identifier] indicates an optional identifier that can be up to 8 characters.
    1. To start the angel process without naming it, use the following command:
      START BBGZANGL[.identifier]
    2. To start the angel process as a named angel process, code the NAME parameter on the operator START command. For example:
      START BBGZANGL[.identifier],NAME=<named_angel>
      The angel process name is 1 - 54 characters inclusive, and must use only the following characters: A-Z 0-9 ! # $ + - / : < > = ? @ [ ] ˆ _ ` { } | ˜
    Note: A Liberty server can use its own named angel process. One benefit of this isolation is that the angel process can be serviced without affecting any other Liberty server instances on the LPAR. The angel process must be running before the Liberty JVM server starts.
  4. Start the Liberty JVM server. By default, the server connects to the unnamed angel process if one is available. To connect to a specific angel process, set the com.ibm.ws.zos.core.angelName property in the JVM server profile, for example:
    -Dcom.ibm.ws.zos.core.angelName=named_angel
  5. You can specify that CICS checks for the presence of a running angel process before enabling, by setting the com.ibm.ws.zos.core.angelRequired property in the JVM server profile to true. For example:
    -Dcom.ibm.ws.zos.core.angelRequired=true
    The server fails if the angel process is not available during startup. Use of this property allows a quicker and cleaner failure.

Interacting with the angel process started task

In the following examples, [.identifier] indicates an optional identifier that can be up to eight characters.
  • Display the Liberty JVM servers that are connected to the angel process:
    MODIFY BBGZANGL[.identifier],DISPLAY,SERVERS,PID

    A list of job names and process identifiers (PID) are displayed:

    15.48.45 STC82204  CWWKB0067I ANGEL DISPLAY OF ACTIVE SERVERS                  
15.48.45 STC82204  CWWKB0080I ACTIVE SERVER ASID 5c JOBNAME IYK3ZNA1 PID 83953428
15.48.45 STC82204  CWWKB0080I ACTIVE SERVER ASID 5c JOBNAME IYK3ZNA1 PID 33621002

    Each Liberty JVM server runs under a unique PID, and is returned by the CICS command INQUIRE JVMSERVER.

  • Stop the angel process.
    STOP BBGZANGL[.identifier]
Note: The Liberty JVM server must be stopped before restarting or applying maintenance to the angel process.

SAF profiles used by the angel process

This section describes the SAF profiles to which access is required for CICS processing. For information on the full set of SAF profiles defined by Liberty, refer to Enabling z/OS authorized services on Liberty for z/OS.

  • The Liberty JVM server runs under the authority of the CICS region user ID. This user ID must be able to connect to the angel process to use authorized services. The user ID that the angel process runs under needs access to the SAF STARTED profile, for example: 
    RDEFINE STARTED BBGZANGL.* UACC(NONE) STDATA(USER(WLPUSER))
SETROPTS RACLIST(STARTED) REFRESH
  • For the Liberty JVM server to connect to an angel process, create a profile for the angel (BBG.ANGEL, or BBG.ANGEL.<namedAngelName> if you are using a named angel process) in the SERVER class. Give the CICS region user ID (cics_region_user) authority to access it, for example, in RACF®: 
    RDEFINE SERVER BBG.ANGEL UACC(NONE)
PERMIT BBG.ANGEL CLASS(SERVER) ACCESS(READ) ID(cics_region_user)
  • For a Liberty server to use the z/OS authorized services, create a SERVER profile for the authorized module BBGZSAFM and give the CICS region user ID (cics_region_user) to the profile:
    RDEFINE SERVER BBG.AUTHMOD.BBGZSAFM UACC(NONE)
PERMIT BBG.AUTHMOD.BBGZSAFM CLASS(SERVER) ACCESS(READ) ID(cics_region_user)
  • Give the Liberty JVM server, under the authority of the CICS region user ID (cics_region_user), access to the SAF user registry and SAF authorization services (SAFCRED) in the SERVER class. For example, in RACF:
    RDEFINE SERVER BBG.AUTHMOD.BBGZSAFM.SAFCRED UACC(NONE)
PERMIT BBG.AUTHMOD.BBGZSAFM.SAFCRED CLASS(SERVER) ACCESS(READ) ID(cics_region_user)
  • Create a SERVER profile for the IFAUSAGE services (PRODMGR) and allow the CICS region user ID access to it. This allows the Liberty JVM server to register and unregister from IFAUSAGE when the CICS JVM server is enabled and disabled:
    RDEFINE SERVER BBG.AUTHMOD.BBGZSAFM.PRODMGR UACC(NONE)
PERMIT BBG.AUTHMOD.BBGZSAFM.PRODMGR CLASS(SERVER) ACCESS(READ) ID(cics_region_user)
  • Refresh the SERVER resource:
    SETROPTS RACLIST(SERVER) REFRESH
The following table summarizes the SAF security profiles used by a Liberty server running in a CICS JVM server.
Table 1. SAF profile table for CICS Liberty security
Class Profile CICS region user ID  1  Unauthenticated user ID  2  Authenticated user ID  3 
Required for angel process registration at Liberty server startup
SERVER BBG.ANGEL READ    
SERVER BBG.ANGEL.<namedAngelName> READ    
SERVER BBG.AUTHMOD.BBGZSAFM READ    
SERVER BBG.AUTHMOD.BBGZSAFM.SAFCRED READ    
SERVER BBG.AUTHMOD.BBGZSAFM.PRODMGR READ    
Required for authentication or authorization
SERVER BBG.SECPFX.BBGZDFLT  4  READ    
APPL BBGZDFLT  4    READ READ
EJBROLE BBGZDFLT.<resource>.<role> 5      READ
  1. User ID that is associated with the CICS job or started task.
  2. User ID used for unauthenticated requests in Liberty. The value is controlled using the unauthenticatedUser attribute of the <safCredentials> element. This defaults to WSGUEST.
  3. User ID authenticated by the Liberty server.
  4. BBGZDFLT is the default value for the security profile prefix which is set using the profilePrefix attribute of the <safCredentials> element, for example: <safCredentials profilePrefix="BBGZDFLT"/>.
  5. EJBROLE profiles are required if the <safAuthorization> element is configured. The default pattern for the profile is controlled by the SAF role mapper element which defaults to <safRoleMapper profilePattern="%profilePrefix%.%resource%.%role%"/>.

For more information, see Liberty: Process types on z/OS.