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.
Running the angel process started task
- Locate the JCL procedure for the started task in the USSHOME directory, for example:
/usr/lpp/cicsts54/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/cicsts54/wlp
- Start the angel process. In the following examples,
[.identifier]
indicates an optional identifier that can be up to 8 characters.- To start the angel process without naming it, use the following command:
START BBGZANGL[.identifier]
- To start the angel process as a named angel process, code the NAME parameter on the operator START command. For example:
The angel process name is 1 - 54 characters inclusive, and must use only the following characters: A-Z 0-9 ! # $ + - / : < > = ? @ [ ] ˆ _ ` { } | ˜START BBGZANGL[.identifier],NAME=<named_angel>
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. - To start the angel process without naming it, use the following command:
- 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:
The server fails if the angel process is not available during startup. Use of this property allows a quicker and cleaner failure.-Dcom.ibm.ws.zos.core.angelRequired=true
Interacting with the angel process started task
[.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]
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
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 |
- User ID that is associated with the CICS job or started task.
- User ID used for unauthenticated requests in Liberty. The value is controlled using the
unauthenticatedUser
attribute of the<safCredentials>
element. This defaults toWSGUEST
. - User ID authenticated by the Liberty server.
BBGZDFLT
is the default value for the security profile prefix which is set using theprofilePrefix
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 Liberty: Process types on z/OS.