Configuring the Liberty Angel process and z/OS authorized services

You need to configure the Liberty Angel process so that z/OS® Connect Enterprise Edition can use z/OS authorized services.

About this task

To use z/OS authorized services such as System Authorization Facility (SAF), Workload Manager (WLM), Resource Recovery services (RRS), SVCDUMP, or WebSphere® Optimized Local Adapters (WOLA) you must set up a Liberty Angel process and grant access for your z/OS Connect EE server to use these services. SAF is used by Liberty security mechanisms to call RACF®. RRS is used by IBM® MQ resource adapter when the connection to IBM® MQ is made in BINDINGS mode.

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 z/OS Connect EE 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: 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 z/OS Connect EE 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.

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 z/OS Connect EE 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 z/OS Connect EE 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 z/OS Connect EE 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 z/OS Connect EE server authority to use the required z/OS authorized services.
    Define the following SAF SERVER profiles. Grant your z/OS Connect EE server user ID READ access to each, by using the following commands, where server_id is the user ID used to run the z/OS Connect EE 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 z/OS Connect EE 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 z/OS Connect EE 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 the authorized client module BBGZSCFM.
      RDEF SERVER BBG.AUTHMOD.BBGZSCFM UACC(NONE)
      PERMIT BBG.AUTHMOD.BBGZSCFM 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 IFAUSAGE services (PRODMGR)
      RDEF SERVER BBG.AUTHMOD.BBGZSAFM.PRODMGR UACC(NONE)
      PERMIT BBG.AUTHMOD.BBGZSAFM.PRODMGR 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, you must grant WebSphere Liberty Profile ALTER access to the MVSADMIN.RRS.COMMANDS resource in the RACF® FACILITY class.
  4. Optional: If you wish to enable the AsyncIO on z/OS (ZOSAIO) service, configure security to permit your z/OS Connect EE 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 Asynchronous TCP/IP sockets I/O for Liberty (AsyncIO)

  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 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 z/OS Connect EE 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 be dependant 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 becomes 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 z/OS Connect EE. If servers and applications are left running after the angel started task is stopped, a server hang condition can occur.