The Liberty angel process

The Liberty angel process is a started task that allows Liberty servers to use z/OS authorized services. It's long-lived and can be shared among your multiple Liberty servers. 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).

Named angels

A Liberty server can only connect to one angel process at server startup. However, all 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. To achieve this, you need to use named angels.

If an angel process is not given a name, it becomes the default angel process. You can have only one default angel process. If you try to create another, it fails to start.

Optionally, you can name an angel process. Named angels allow multiple uniquely named angel processes to run on a single z/OS system, in addition to the default unnamed angel process.

A named angel has the same function as the default angel process, but it can be used for a selected group of Liberty servers. This provides the ability to isolate servers from one another, so that they can run different service levels or be managed independently.

For more information about named angel processes, see Named angel.

Angel version interoperability

All Liberty servers that are running on a z/OS image can share a single angel process, regardless of the level of Liberty code that the servers are using. It's recommended that the angel process be upgraded before the Liberty servers that use its services, because it provides back-level support for earlier versions of Liberty servers. This ensures support is available for all authorized services potentially required by the Liberty servers.

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.

You can identify the version of Liberty for the angel process and the Liberty JVM server that's running in CICS as shown in Examples of identifying Liberty versions.

Running the angel process started task

Locate the JCL procedure for the started task in the USSHOME directory, for example: /usr/lpp/cicsts56/wlp/templates/zos/procs/bbgzangl.jcl
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/cicsts56/wlp
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.
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
```
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 use the following console command:

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 that are used by a Liberty server running in a CICS JVM server.

Table 1. SAF profile table for CICS Liberty security
Class	Profile	Required for	CICS region user ID 1	Unauthenticated user ID 2	Authenticated user ID 3
SERVER	`BBG.ANGEL`	Angel process registration at Liberty server startup	READ
SERVER	`BBG.ANGEL.<namedAngelName>`	Angel process registration at Liberty server startup	READ
SERVER	`BBG.AUTHMOD.BBGZSAFM`	Angel process registration at Liberty server startup	READ
SERVER	`BBG.AUTHMOD.BBGZSAFM.SAFCRED`	Angel process registration at Liberty server startup	READ
SERVER	`BBG.AUTHMOD.BBGZSAFM.PRODMGR`	Angel process registration at Liberty server startup	READ
SERVER	`BBG.SECPFX.BBGZDFLT` 4	Authentication or authorization	READ
APPL	`BBGZDFLT` 4	Authentication or authorization		READ	READ
EJBROLE	`BBGZDFLT.<resource>.<role>` 5	Authentication or authorization			READ

User ID that is associated with the CICS job or started task.
User ID used for unauthenticated requests in Liberty. The value is controlled by using the unauthenticatedUser attribute of the <safCredentials> element. This value defaults to WSGUEST.
User ID authenticated by the Liberty server.
BBGZDFLT is the default value for the security profile prefix that is set by using the profilePrefix attribute of the <safCredentials> element, for example: <safCredentials profilePrefix="BBGZDFLT"/>.
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 Process types on z/OS.

Examples of identifying Liberty versions

Example: Identifying the angel Liberty version from the started task system log

If the Liberty angel process is running Liberty 18.0.0.2 or above, the started task system log contains a message that indicates the Liberty version:

CWWKB0079I THE ANGEL BUILD LEVEL IS 18.0.0.2 20180619-0654 2018.7.0.0 20180619-0654

Example: Identifying the version of a Liberty JVM server running in CICS from message DFHSJ1405

The version of a Liberty running in a CICS JVM server is available in the following message:

DFHSJ1405I 08/22/2018 17:04:39 IYK3ZDRI JVMSERVER EYUCMCIJ is running WebSphere Application Server 
                            Version 18.0.0.2 Liberty - (18.0.0.2-cl180220180619-0403) process ID 67174497.

Example: Identifying both Liberty versions by running scripts

Suppose that the angel JCL specifies the following ROOT parameter:


// SET ROOT='/usr/lpp/zosmf/wlp'

To find out what the version of Liberty for the angel process is, run the following script:


/usr/lpp/zosmf/wlp/bin/productInfo version --verbose

For a Liberty JVM server running in CICS, run the following script:

/usr/lpp/cicsts56/wlp/bin/productInfo version --verbose

Figure 1. Example output


WebSphereApplicationServer.properties:
        com.ibm.websphere.productId=com.ibm.websphere.appserver
        com.ibm.websphere.productOwner=IBM
        com.ibm.websphere.productVersion=16.0.0.3
        com.ibm.websphere.productName=WebSphere Application Server
        com.ibm.websphere.productInstallType=Archive
        com.ibm.websphere.productEdition=zOS
        com.ibm.websphere.productLicenseType=IPLA

WebSphereApplicationServerZOS.properties:
        com.ibm.websphere.productId=com.ibm.websphere.appserver.zos
        com.ibm.websphere.productOwner=IBM CORP
        com.ibm.websphere.productVersion=16.0.0.3             <== Liberty Version    
        com.ibm.websphere.productName=WAS FOR Z/OS
        com.ibm.websphere.productPID=5655-WAS
        com.ibm.websphere.productQualifier=WAS Z/OS
        com.ibm.websphere.productReplaces=com.ibm.websphere.appserver
        com.ibm.websphere.productEdition=
        com.ibm.websphere.gssp=true

zOSMF.properties:
        com.ibm.websphere.productId=com.ibm.zoszmf
        com.ibm.websphere.productOwner=IBM
        com.ibm.websphere.productVersion=2.2.0
        com.ibm.websphere.productName=z/OSMF
        com.ibm.websphere.productPID=5650-ZOS
        com.ibm.websphere.productQualifier=z/OSMF
        com.ibm.websphere.productReplaces=com.ibm.websphere.appserver.zos
        com.ibm.websphere.productEdition=N/A