Configuring the Liberty Angel process and z/OS authorized services

You must configure the Liberty Angel process so that z/OS® Connect (OpenAPI 2) can use z/OS authorized services.

About this task

To use z/OS authorized services, you must set up a Liberty Angel process and grant access for your IBM® z/OS Connect server to use these services. IBM z/OS Connect uses the following z/OS authorized services:
  • LOCALCOM - Required to use WebSphere Optimized Local Adapters (WOLA).
  • SAFCRED - Required to use SAF authorized user registry services and SAF authorization services.
  • TXRRS - Required by the IBM MQ resource adapter when the connection to IBM MQ is made in BINDINGS mode. For more information, see Using the IBM MQ service provider.
  • WOLA - Required to use WebSphere Optimized Local Adapters (WOLA).
  • ZOSAIO - Required to use AsyncIO on z/OS. For more information, see Enabling Asynchronous TCP/IP sockets I/O for Liberty on z/OS
  • ZOSDUMP - Only required if asked to obtain an SVC dump by IBM service. It provides access to SVCDUMP services.
  • ZOSWLM - Required to use WLM services. For more information, see Measuring API workloads with WLM.

When IBM z/OS Connect connects to an angel process during server startup, it checks that the server has access to the z/OS authorized services. By default, access checks are performed for all authorized services. You can restrict the IBM z/OS Connect server to check and use only the authorized services it requires, which then makes other authorized services unavailable. You can specify the required authorized services by using the bootstrap.properties file property com.ibm.ws.zos.core.angelRequiredServices. The value for this property must be a comma-separated list of valid angel process services, as described above. All service names must be 8 characters or less and symbols are not valid. This property must be specified with com.ibm.ws.zos.core.angelRequired property set to true.

For example, to require only the SAFCRED and ZOSAIO authorized services specify: 
com.ibm.ws.zos.core.angelRequiredServices=SAFCRED,ZOSAIO

If you specify the SAFLOG=Y JCL parameter on the angel PROC, SAF error messages are issued for authorized services that are checked and that a server is not allowed to use. The default is SAFLOG=N.

For more information, see Process types on z/OS in the WebSphere Application Server for z/OS Liberty documentation.

The Liberty profile Angel process must be run as a started task, but is lightweight, has no configuration or TCP ports, and consumes almost no CPU.

To create the Angel process started task, you must customize the sample JCL and create SAF definitions to associate the started task with a user ID and authorize your IBM z/OS Connect server to use the z/OS authorized services. The following examples use RACF® commands. Two copies of the sample JCL are provided, hlq.SBAQSAMP(BAQZANGL) and <installation_path>/wlp/templates/zos/procs/bbgzangl.jcl but they provide the same function.

Note:
  1. Each LPAR can have multiple named Angel processes but only one default Angel process. Ensure that the Angel processes are running at the most recent installed level of Liberty on the LPAR. If a Liberty server instance that is embedded in IBM z/OS Connect server connects to an Angel process that is running at an earlier service level, some features of the server might not be available. For more information about named angels, see Configuring named angels.
  2. The Liberty authorized services PRODMGR group allows authorized calls to be made to the z/OS IFAUSAGE API, which is used to write SMF type 89 (product utilization) records. The SMF type 89 records are used as input to the Sub-Capacity Reporting Tool (SCRT). IBM z/OS Connect can write the SMF type 89 records as an authorized, or unauthorized user. A IBM z/OS Connect server can write the required SMF type 89 records whether it has access to the PRODMGR group or not. To enable the PRODMGR services, see Enabling z/OS authorized services on Liberty for z/OS in the Liberty documentation.

Procedure

  1. Create the JCL start procedure for the Angel process.
    1. To set up the started task, customize the sample JCL provided in <hlq>.SBAQSAMP(BAQZANGL) and add it to your PROCLIB library.
    2. Customize the sample JCL by updating the SET ROOT value to your IBM z/OS Connect installation directory.
      The sample JCL defines the default directory: 
      SET ROOT='/usr/lpp/IBM/zosconnect/v3r0/wlp'

In the following steps, work with your security administrator to create the necessary authorizations and artifacts for the Angel process to run as a started task and to authorize your IBM z/OS Connect server to use z/OS authorized services.

  1. Started tasks must be associated with a user ID. If you do not have a suitable user ID, use the following commands to create a new user ID and group.
    For example, to define a user ID called angel_id in a group called admin_group, your security administrator needs to enter the following commands:
    ADDGROUP admin_group OMVS(GID(gid))
    ADDUSER angel_id DFLTGRP(admin_group) OMVS(UID(uid)  HOME(/u/angel_id) PROGRAM(/bin/sh)) NAME('Liberty angel') NOPASSWORD NOOIDCARD

    The user ID used to run the angel process requires read and execute permissions to the IBM z/OS Connect UNIX System Services installation directory.

  2. Grant the required SAF authorization to associate the user ID with the started task.
    For example,
    RDEF STARTED BAQZANGL.* UACC(NONE) STDATA(USER(angel_id) GROUP(admin_group) PRIVILEGED(NO) TRUSTED(NO) TRACE(YES))
    SETROPTS RACLIST(STARTED) REFRESH
  3. Create a set of SAF SERVER profiles to grant your IBM z/OS Connect server authority to use the required z/OS authorized services.
    Define the following SAF SERVER profiles. Grant your IBM z/OS Connect server user ID READ access to each, by using the following commands, where server_id is the user ID used to run the IBM z/OS Connect server started task.

    You can authorize access at a group level, by replacing server_id with the name of the group. The user ID used to run the IBM z/OS Connect server started task must be connected to this group.

    • SERVER profile for the angel process to authorize the server_id user ID read access to it. This action grants a IBM z/OS Connect server access to the angel process, which is required for the z/OS authorized services. You can create a named or unnamed angel server profile. If you are using both named and unnamed angels, you must define an angel server profile for each.
      • To create an unnamed angel server profile and enable a server that is running as server_id to connect to it, enter the following commands.
        RDEF SERVER BBG.ANGEL UACC(NONE)
        PERMIT BBG.ANGEL CLASS(SERVER) ACCESS(READ) ID(server_id)
      • To create a named angel server profile and enable a server that is running as server_id to connect to it, enter the following commands.
        RDEF SERVER BBG.ANGEL.<namedAngelName> UACC(NONE)
        PERMIT BBG.ANGEL.<namedAngelName>  CLASS(SERVER) ACCESS(READ) ID(server_id)

      The profile name that you specify for the namedAngelName variable is the name of the new angel. You can use generic profiles such as BBG.ANGEL.* to grant a user ID access to multiple named angels.

    • SERVER profile for the authorized module BBGZSAFM to allow server access to z/OS authorized services.
      RDEF SERVER BBG.AUTHMOD.BBGZSAFM UACC(NONE)
      PERMIT BBG.AUTHMOD.BBGZSAFM CLASS(SERVER) ACCESS(READ) ID(server_id)
    • SERVER profile for WLM services (ZOSWLM).
      RDEF SERVER BBG.AUTHMOD.BBGZSAFM.ZOSWLM UACC(NONE)
      PERMIT BBG.AUTHMOD.BBGZSAFM.ZOSWLM CLASS(SERVER) ACCESS(READ) ID(server_id)
    • SERVER profile for RRS transaction services (TXRRS).
      RDEF SERVER BBG.AUTHMOD.BBGZSAFM.TXRRS UACC(NONE)
      PERMIT BBG.AUTHMOD.BBGZSAFM.TXRRS CLASS(SERVER) ACCESS(READ) ID(server_id)
    • SERVER profile for SVCDUMP services (ZOSDUMP).
      RDEF SERVER BBG.AUTHMOD.BBGZSAFM.ZOSDUMP UACC(NONE)
      PERMIT BBG.AUTHMOD.BBGZSAFM.ZOSDUMP CLASS(SERVER) ACCESS(READ) ID(server_id)
    • SERVER profile for SAF authorized user registry services and SAF authorization services (SAFCRED).
      RDEF SERVER BBG.AUTHMOD.BBGZSAFM.SAFCRED UACC(NONE)
      PERMIT BBG.AUTHMOD.BBGZSAFM.SAFCRED CLASS(SERVER) ACCESS(READ) ID(server_id)
    Note: If you use the IBM MQ for z/OS service provider that is delivered with IBM MQ, or the IBM MQ for z/OS service provider that is delivered with IBM z/OS Connect, you must grant WebSphere Liberty Profile ALTER access to the MVSADMIN.RRS.COMMANDS resource in the RACF® FACILITY class.
  4. Optional: To enable the AsyncIO on z/OS (ZOSAIO) service, configure security to permit your IBM z/OS Connect server to use the authorized AsyncIO service.
    For example,
    RDEF SERVER BBG.AUTHMOD.BBGZSAFM.ZOSAIO UACC(NONE)
    PERMIT BBG.AUTHMOD.BBGZSAFM.ZOSAIO CLASS(SERVER) ACCESS(READ) ID(server_id)

    For more information, see ../performance/configuration_parameters.html#configuration_parameters__asyncio in the topic Configuration parameters.

  5. Optional: If you are using WOLA, you must also create the following profiles.
    • SERVER profiles for the optimized local adapter authorized service.
      RDEF SERVER BBG.AUTHMOD.BBGZSAFM.LOCALCOM UACC(NONE)
      PERMIT BBG.AUTHMOD.BBGZSAFM.LOCALCOM CLASS(SERVER) ACCESS(READ) ID(server_id)
      RDEF SERVER BBG.AUTHMOD.BBGZSAFM.WOLA UACC(NONE)
      PERMIT BBG.AUTHMOD.BBGZSAFM.WOLA CLASS(SERVER) ACCESS(READ) ID(server_id)
    • SERVER profile for the authorized client module BBGZSCFM.
      RDEF SERVER BBG.AUTHMOD.BBGZSCFM UACC(NONE)
      PERMIT BBG.AUTHMOD.BBGZSCFM CLASS(SERVER) ACCESS(READ) ID(server_id)
    • SERVER profiles for optimized local adapter authorized client service.
      RDEF SERVER BBG.AUTHMOD.BBGZSCFM.WOLA UACC(NONE)
      PERMIT BBG.AUTHMOD.BBGZSCFM.WOLA CLASS(SERVER) ACCESS(READ) ID(server_id)
  6. Refresh to activate the definitions:
    SETROPTS RACLIST(SERVER) REFRESH
  7. Start the Angel process as a started task:
    From the z/OS operator console, enter the following command:
    S BAQZANGL
    The following log messages indicate that the Angel process started successfully:
    IRR812I PROFILE BAQZANGL.* (G) IN THE STARTED CLASS WAS USED
TO START BAQZANGL WITH JOBNAME BAQZANGL.
$HASP100 BAQZANGL ON STCINRDR
IEF695I START BAQZANGL WITH JOBNAME BAQZANGL IS ASSIGNED TO
USER angel_id, GROUP admin_group
$HASP373 BAQZANGL STARTED
CWWKB0056I INITIALIZATION COMPLETE FOR ANGEL

    Leave the Angel process running for any IBM z/OS Connect server that requires access to z/OS authorized services. To stop the Angel process, enter the following command at the z/OS operator console:

    P BAQZANGL

    Note: Best practice is to NEVER cancel the angel process. Server tasks and application tasks can depend on the angel process running. However, there are rare cases in which to avoid a severe system shutdown, such as a re-IPL, you might find it necessary to cancel the angel process. If it is necessary to cancel the angel started task or if the angel started task abends, your system administrator must cancel all the servers with applications that depend on the angel started task, including IBM z/OS Connect. If servers and applications are left running after the angel started task is stopped, a server hang condition can occur.