2 Deploying the Agents of the CA ACF2 Connector on the Target System

Install the Pioneer Provisioning Agent and the Voyager Reconciliation Agent components of the CA ACF2 connector on the mainframe.

The following sections provide more information about installing, configuring, and using agents:

Deployment Requirements

These are the deployment requirements for installing Pioneer and Voyager.

Before installing, refer the README that is contained in the connector installation media to learn about the new features, enhancements, and bug fixes. The following sections describe the installation and configuration of these agents:

Verifying Deployment Requirement

The following table lists the hardware, software, and authorization requirements for installing the Provisioning Agent - Pioneer and the Reconciliation Agent - Voyager.

Table 2-1 Deployment Requirements

Item Requirement
Operating System IBM z/OS 2.2, 2.3
Message Transport Layer TCP/IP
ACF2 Identity Repository Verify that the current PUT for z/OS is installed.
Target system user account for the Reconciliation and Pioneer Agents ACF2-authorized user account with System Administrators privileges.
z/OS LE Pioneer and Voyager are written using LE, and the System LE run options must be correct for proper execution.
Started Tasks Both the Voyager and Pioneer Agents need a started task and a service account that has the privileges required to run the CA ACF2 system commands on the mainframe system. In addition, these agents function under a user account on the mainframe system. This user account must be created by the systems programmer before you deploy the agents.

Note:

Both Voyager and Pioneer user accounts must be placed into the ACF2 database. These user accounts must have at least the permissions of the System Administrators group on the mainframe. These user accounts have permissions above those of ordinary administrators on the mainframe, which include Read, Write, Execute, and Modify privileges

Environmental Settings and Requirements

Ensure that the following requirements are met on the mainframe:

  • Voyager and Pioneer each require approximately a 2-megabyte Region to work. Additionally, a subpool is created to contain Reconciliation changes for Voyager to access and send LDAP gateway. The subpool is in the ECSA and is generally small and is a temporary staging area for reconciliation requests. If there is an outage, Voyager saves the subpool to the //CACHESAV ddname specified in the Voyager STC, and when Voyager is restarted and the subpool is rebuilt, the CACHESAV file is reloaded into the subpool. Once the LDAP connects, the subpool data is sent to the LDAP.
  • An ACF2 (LID) userid profile is required to start both Pioneer and Voyager. An ACF2 userid or LID for Pioneer requires special privileges. It acts as an ACF2 administrator with ‘ACCOUNT and SECURITY’ privileges.
  • Voyager operates by using the following three standard ACF2 exits:
    • LIDPOST
    • NEWPXIT
    • EXPPXIT
  • z/OS LE run options: ALL31 (ON) and STACK (131072,131072,ANYWHERE,KEEP,524288,524288). If the LE options are incorrect, it will result in a Pioneer or Voyager abend.
    Maintaining a specific password format is an example of the objective for which you use custom exits. CA ACF2 exits are engineered to be the last exits called in sequence, that allow existing exits to function normally. All of the exits used IDFACF2P(NEWPXIT), IDFACF2X(EXPPXIT), and IDFACF2E(LIDPOST) must be copied to an LPA Library, and then an IPL of z/OS is required to activate the exits. In addition, you require a module named "IDFCACHE" for all three exits to function properly. It must also reside in the same LPA library as the exits. A ‘SET PROG’ member is then used to activate them.

    Note:

    A system programmer must perform an IPL after a system component is changed or modified.

Installing the Mainframe Agents

The CA ACF2 Advanced connector is shipped with a pair of agents, one for provisioning and one for real-time reconciliation. If real-time reconciliation is not required, then install and start only the provisioning agent.

Before installation, review the Deployment Requirements section.
  1. Extract the contents of the ACF2-AGENTS-<TIMESTAMP>-<VERSION>.zip file located in the connector installation media on to the computer hosting the mainframe.
    The following files will be extracted:
    • CLISTLIB.XMIT
    • JCLLIB.XMIT
    • LINKLIB.XMIT
    • PARMLIB.XMIT
    • PROCLIB.XMIT
  2. Transmit the XMIT files extracted in the previous step to z/OS.
    Use the following specifications during transmission:
    • RECFM=FB
    • LRECL=80
    • BLKSIZE=3120
    • DSORG=PS
    For example, you may use 3270 or FTP to transfer the files.
    The following datasets will exist on z/OS:
    • <HLQ>.CLISTLIB.XMIT
    • <HLQ>.JCLLIB.XMIT
    • <HLQ>.LINKLIB.XMIT
    • <HLQ>.PARMLIB.XMIT
    • <HLQ>.PROCLIB.XMIT

    Note:

    <HLQ> is the high-level-qualifier used when transmitting the files to z/OS.
  3. For each of the files transmitted in the previous step, execute the following command at the TSO prompt: TSO RECEIVE INDA('<HLQ>.<FILE>.XMIT'). When prompted to specify restore parameters, enter DA('<HLQ>.<FILE>').
    For example, if the high-level qualifier is IDF and the file is CLISTLIB.XMIT, execute the following command: TSO RECEIVE INDA('IDF.CLISTLIB.XMIT'), and when prompted, respond with: DA('IDF.CLISTLIB').
    The following datasets will exist on z/OS:
    • <HLQ>.CLISTLIB
    • <HLQ>.JCLLIB
    • <HLQ>.LINKLIB
    • <HLQ>.PARMLIB
    • <HLQ>.PROCLIB

    Note:

    In the preceding datasets, replace <HLQ> with the high-level-qualifier used when receiving the previously transmitted files.
  4. Edit each of the following installed job streams and provide values for any placeholders in them.
    • <HLQ>.CLISTLIB.ENVINFO
    • <HLQ>.JCLLIB.CREATDSN
    • <HLQ>.JCLLIB.CRTLOGDN
    • <HLQ>.JCLLIB.IEBCOPYL
    • <HLQ>.JCLLIB.IEBCOPYP
    • <HLQ>.JCLLIB.IEBCPYPR
    • <HLQ>.JCLLIB.KEYMODR
    • <HLQ>.PARMLIB.PROGID
    • <HLQ>.PROCLIB.PIONEER
    • <HLQ>.PROCLIB.STARTUP
    • <HLQ>.PROCLIB.VOYAGER
    • <HLQ>.PROCLIB.WRAPUP
    • <HLQ>.JCLLIB.LOADDSN1

    Note:

    Replace <HLQ> with the high-level-qualifier used when receiving the previously transmitted files.
    The following table lists the installation placeholders, their description, and example.

    Table 2-2 Installation Placeholders

    Placeholder Description Example
    ++hlq++ The high-level qualifier where the product is to be installed. If there are multiple segments, all should be included. IDF
    ++vol++ The volume where the product is to be installed. SDWRK1
    ++lpalib++ The DSN of the data set that contains customized lpalibs. Customize based on z/OS environment. USER.LPALIB
    ++parmdtr++ The name of the PARMLIB XMIT that was transmitted to z/OS (without the .XMIT). <HLQ>.PARMLIB
    ++parmlib++ The DSN of the data set that contains customized parmlibs. Customize based on z/OS environment. USER.PARMLIB
    ++procdtr++ The name of the PROCLIB XMIT that was transmitted to z/OS (without the .XMIT). <HLQ>.PROCLIB
    ++proclib++ The DSN of the data set that contains customized proclibs. Customize based on z/OS environment. USER.PROCLIB
    ++linkdtr++ The name of the LINKLIB XMIT that was transmitted to z/OS (without the .XMIT). <HLQ>.LINKLIB
    ++linklib++ The DSN where the LINKLIB XMIT that was received. <HLQ>.LINKLIB
    ++rexxdtr++ The name of the CLISTLIB XMIT that was transmitted to z/OS (without the .XMIT). <HLQ>.CLISTLIB
    ++rexxlib++ The DSN where the CLISTLIB XMIT that was received. <HLQ>.CLISTLIB
    ++pionprms++ The DSN of the control (configuration) file for the provisioning agent. PIONEER.CONTROL.FILE
    ++voyprms++ The DSN of the control (configuration) file for the reconciliation agent. VOYAGER.CONTROL.FILE

    Note:

    Replace <HLQ> with the high-level-qualifier used when receiving the previously transmitted files.
    For example, in the following snippet from CREATEDSN, replace the placeholders ++hlq++ and ++vol++ with values such as IDF and SDWRK1: 
    //*
//S1       SET  PHLQ=++hlq++.PIONEER
//S2       SET  VHLQ=++hlq++.VOYAGER
//S3       SET  PVOL=++vol++
//S4       SET  VVOL=++vol++
//*
    The following snippet displays the placeholders replaced with values: 
    //*
//S1       SET  PHLQ=IDF.PIONEER
//S2       SET  VHLQ=IDF.VOYAGER
//S3       SET  PVOL=SDWRK1
//S4       SET  VVOL=SDWRK1
//*
  5. Execute each of the following job streams in the order as shown in the following table to complete installation.

    Table 2-3 Job Streams to Execute

    Job Stream Description
    <HLQ>.JCLLIB.IEBCOPYP Copies PARMLIB members to user PARMLIB.
    <HLQ>.JCLLIB.IEBCPYPR Copies PROCLIB members to user PROCLIB.
    <HLQ>.JCLLIB.IEBCOPYL Copies exit routines to use LPA library.
    <HLQ>.JCLLIB.CREATDSN Allocates run time data sets, deleting the data sets first if they already exist.
    <HLQ>.JCLLIB.LOADDSN1 Copies PIONEER & VOYAGER configuration (control) files.
    <HLQ>.JCLLIB.ACF2DEL Deletes pre-existing users and data sets that are overwritten by the installation.
    <HLQ>.JCLLIB.ACF2DEF Defines users and permissions required to run the mainframe agent STCs.

    Note:

    In the above, replace <HLQ> with the high-level-qualifier used when receiving the previously transmitted files.
The installation of the provisioning and reconciliation agents is complete. At this point, you can optionally remove the XMIT datasets that were originally transmitted to z/OS.

Configuring the Mainframe Agents

After installing Pioneer and Voyager, you must configure the mainframe agents to receive requests from the gateway and to also send responses to the gateway.

This section discusses the following topics:

Configuring the Provisioning Agent

You must configure the provisioning agent to receive requests from the LDAP gateway (which comes from OIM).

Edit the <HLQ>.PIONEER.CONTROL.FILE file to configure the behavior of the provisioning agent. <HLQ> is the high-level-qualifier that is specified when you install the agents. See Installing the Mainframe Agents for more information.

Table 2-4 Provisioning Agent Parameters

Parameter Value Description
TCPN TCPIP The name of the TCP/IP STC where the agent is executing.
IPAD 0.0.0.0 Do not change.
PORT 9999 The TCP/IP port that the agent will listen on.
CRLF Y or N Must be set to Y for version 6+ of the LDAP Gateway. Set to N for version 5.
DEBUG Y or N Y turns on debugging and output goes to //DEBUGOUT. Beware as DEBUG=Y produces a lot of output and is not recommended unless instructed by technical personnel.
ESIZE 16 This is the only valid value. This parameter is for the AES128 encryption and decryption.
POST_PROC_ALIAS T or F If T, all LDAP Alias requests are processed. If F, all LDAP Alias requests are rejected.
IDLEMSG Y or N If set to Y, an idle message displays every hour. if set to N, idle messages are not displayed on the log.
DEBUGOUT SYSOUT, CLASS (X) X should be a single character, valid JES2 class. Used when DEBUG=Y is specified.
SPIN_CLASS X X should be a single character, valid JES2 class. Used when DEBUG=Y is changed to DEBUG=Y via the modify command.
AUDIT AUDIT=YES,SYSOUT,CLASS(X) when audit logs are needed or NO If set to YES, records are sent to //AUDTLOG. If set to NO, //AUDTLOG is not generated and no audit logs are recorded.
FILTER YES or NO If set to NO, no filtering of inbound LDAP requests is performed. If set to YES, the F1 and F2 parameters are examined for filter criteria.
F1 Up to 8 comma-separated values ACF2 INSERTs and CHANGEs are examined for these values. The supported values are the standard ACF2 attributes for the LID. For example, SECURITY, AUDIT, READALL. If request containing values specified in F1 are encountered, PIONEER rejects those requests.
F2 See F1 See F1

Configuring the Reconciliation Agent

You must configure the reconciliation agent to send incremental responses to the gateway.

Edit the <HLQ>.VOYAGER.CONTROL.FILE file to configure the behavior of the reconciliation agent. <HLQ> is the high-level-qualifier specified when installing the agents. See Installing the Mainframe Agents for more information.

Table 2-5 Reconciliation Agent Parameters

Parameter Value Description
SUBPOOL_SIZE 0200K to 7500K Subpool size desired for storage of reconciliation messages captured from exits. This storage is allocated above the 16M line.
TCPN TCPIP The name of the TCP/IP STC where the agent is executing.
IPAD 999.999.999.999 or ldap.example.com LDAP destination IP address or hostname (up to 40 characters).
PORT 9999 LDAP destination port that is listening to the incoming agent messages.
CRLF Y or N Must be set to Y for version 6+ of the LDAP Gateway. Set to N for version 5.
DEBUG Y or N Y turns on debugging and output goes to //DEBUGOUT. Beware as DEBUG=Y produces a lot of output and is not recommended unless instructed by technical personnel.
ESIZE 16 This is the only valid value. This parameter is for the AES128 encryption and decryption.
CACHE_DELAY 0 to 999 This is the number of seconds that Voyager waits between issuing a write socket to the LDAP Gateway. This parameter is only used for installations running Oracle Identity Manager, otherwise the code is 0.
POST_PROC_ALIAS T or F If T, all LDAP Alias requests are processed. If F, all LDAP Alias requests are rejected.
IDLEMSG Y or N If set to Y, an idle message displays every hour. If set to N, no idle messages are logged.
DEBUGOUT SYSOUT, CLASS (X) X should be a single character, valid JES2 class. Used when DEBUG=Y is specified.
AUDIT YES or NO Records output to //AUDTLOG if set to YES.
VOYAGER_ID YES or NO This value will be included in the LDAP logs for diagnostics.
FILTER1 YES or NO Filter reconciliation messages based on the criteria provided. See Understanding the Reconciliation Agent FILTER Parameter.
FILTER2 See FILTER1 See FILTER1.

Understanding the Reconciliation Agent FILTER Parameter

You can configure Voyager to filter responses that are sent to the LDAP gateway.

Voyager has the ability to FILTER command output to the LDAP. The processing sequence is as follows:

FILTER1=YES,A=PREFIX,V=TEST,TEST10

Note:

The values of A= and V= must be less than 10 characters.
When the value of FILTER parameter is set to YES in Voyager, then the following sequence occurs:
  1. Voyager polls the cache area.
  2. Performs a LIST xxxxx ( LID ) from the subpool.
  3. Verifies that the filter=yes.
  4. Scans for the values.
    • If the values match the stored control file values, then the subpool message is not passed to the LDAP.
    • If the value does not match the stored control file values, then the subpool message is passed to the LDAP and is removed.

Activating and Deactivating Reconciliation Exits

You must activate system exits for capturing and reacting to changes in the security system in order to make use of real-time reconciliation and the reconciliation agent.

Activating Reconciliation Exits

Activate the system exits to capture security system changes in real-time.

To do so, run the following command from the z/OS operator interface:

T PROG=78

Deactivating Reconciliation Exits

Deactivate the system exits to disable the reconciliation of real-time changes to the security system.

To do so, run the following command from the z/OS operator interface:

T PROG=79

Operator Interface for Mainframe Agents

Both provisioning and reconciliation agents have an operator interface, and you can control the agents by passing commands through the interface.

The following topics are discussed in this section:

Provisioning Agent Commands

Pass the Pioneer provisioning agent commands through the operator interface to control Pioneer.

Table 2-6 Provisioning Agent Commands

Command Description
T PROG=ID APF authorizes <HLQ>.LINKLIB - required to start the agent.
S PIONEER Starts the agent.
F PIONEER,SHUTDOWN Shuts down the agent.
F PIONEER,STATUS Sends a status request to the agent.
F PIONEER,DEBUG=Y Enables debug-level (detailed) log output.
F PIONEER,DEBUG=N Disables debug-level (detailed) log output.

Note:

This interface through the z/OS modify command is a single-threaded system. Commands are queued and may take a few seconds before the agent acknowledges them.

About Reconciliation Agent Commands

Pass the Voyager reconciliation agent through the operator interface to control Voyager.

Table 2-7 Voyager reconciliation agent commands and their descriptions.

Table 2-7 Reconciliation Agent Commands

Command Description
T PROG=ID APF authorizes <HLQ>.LINKLIB - required to start the agent.
T PROG=78 Activates system exits - required for real-time reconciliation. See Activating and Deactivating Reconciliation Exits.
S VOYAGER Starts the agent.
F VOYAGER,SHUTDOWN Shuts down the agent.
F PIONEER,STATUS Sends a status request to the agent.
F PIONEER,DEBUG=Y Enables debug-level (detailed) log output.
F PIONEER,DEBUG=N Disables debug-level (detailed) log output.
S STARTUP

Creates subpool231 and inserts the IDF Token in storage for storing reconciliation events. This is optional as the same functionality is executed when Voyager is started. See the following note for permissions required to execute STARTUP.
S WRAPUP

Deletes the IDF token and subpool 231 created in storage. This is optional as same functionality is executed when Voyager is shutdown, but can be executed if required explicitly. See the following note for permissions required to execute WRAPUP.

Note:

  • The interface through the z/OS modify command is a single-threaded system. Commands are queued and take a few seconds before the agent acknowledges them.
  • <HLQ> is the high-level-qualifier specified when installing the agents.
  • For STARTUP and WRAPUP commands to execute successfully, provide access to ACF2 default STC ID at site on dataset high level qualifier <HLQ> specified while installing the agents.

    The following are example commands assuming default STC ID as ACFSTCID

    ACF

    SET RULE

    RECKEY <HLQ> ADD(- UID(*********ACFSTCID) READ(A) WRITE(A) EXEC(A))

    F ACF2,RELOAD(<HLQ>)

    END

    Here, ACFSTCID is the LID in UID string. Update UID string as per ACFFDR at you site.

Uninstalling the Mainframe Agents

Uninstalling removes the provisioning and reconciliation agents from the ACF2 connector.

To uninstall Pioneer and Voyager, do the following:
  1. Shut down Pioneer and Voyager.
  2. Execute wrapup (/s wrapup) to ensure subpool231 and IDF token are cleared from storage.
  3. Edit and Run ACF2DEL to delete permissions and requests.
  4. Run Prog79 using /T prog=79 to disable Exits.
  5. Remove APF Authorization to the load library using APF DELETE DSNAME (loadlib) VOLUME (name). This can be achieved by replacing ADD with DELETE in the PROGID member for the corresponding PARMLIB and executing the member through /T PROG=ID from operator console.
  6. Delete XMITs and the corresponding received datasets (LINKLIB,CLISTLIB,JCLLIB,PROCLIB and PARMLIB).