3 Connector Deployment on CA ACF2

You must install the Reconciliation Agent and Provisioning Agent components of the CA ACF2 Advanced connector on the mainframe. The following sections describe the installation and configuration of these agents:

• Verifying Deployment Requirements

• Deploying the Reconciliation Agent and Provisioning Agent

• Installing the Exits for the Reconciliation Agent

• Configuring the Message Transport Layer

3.1 Verifying Deployment Requirements

Both the Reconciliation Agent and Provisioning Agent need a started task and service account that has the privileges required to run CA ACF2 system commands on the mainframe system.

In addition, these agents are accessed by a user account with privileges on the mainframe system. This user account must be created by the systems programmer before you deploy the agents.

Note:

Both the Provisioning Agent and the Reconciliation Agent user accounts require placement into an administrative APF-authorized library. These user accounts must have at least the privileges of the SystemAdministrators group on the mainframe. These user accounts are given permissions above those of ordinary administrators on the mainframe, which include Read, Write, Execute, and Modify privileges.

3.1.1 Environmental Settings and Requirements

Ensure that the following requirements are met on the mainframe:

• The Provisioning Agent and Reconciliation Agent use their own memory subpools to manage peak load conditions. These subpools require 1.5 to 2.0 MB of mainframe memory for operations. You configure this while installing the Provisioning Agent and Reconciliation Agent.

• In addition to the program itself, the user account that a program runs under must also have authorization to access subpools on the host platform. This must be configured by the systems programmer.

• If TCP/IP is used for the message transport layer, then an administrator must have authorization to create ports on the mainframe and provide security authorizations.

• The Reconciliation Agent operates by using user exit technology, outside the mainframe operating system. This means that it runs in a different LPAR from the operating system.

  A command execution is validated through an exit, just before full completion of the native mainframe command. If the exit fails, then the command fails and returns an error message. Maintaining a specific password format is an example of the objective for which you use custom exits. Oracle Identity Manager exits are engineered to be the last exits called in sequence, which allows the existing exits to function normally. After modifying exits within an LPAR, an initial program load (IPL) of the LPAR may be required.

  Note:

  You must perform an IPL operation after a system component, such as an exit, is modified.

3.2 Deploying the Reconciliation Agent and Provisioning Agent

To deploy the Reconciliation Agent and Provisioning Agent:

1. Extract the contents of the following file from the installation media to a temporary directory on any computer:

   etc/Provisioning and Reconciliation Connector/Mainframe_ACF2.zip
   

2. Transmit or FTP the Jcl.xmit and linklib.xmi files to the mainframe, each with the following specifications:

   RECFM=FB, LRECL=80, BLKSIZE=3120, and DSORG=PS

3. Log in to the TSO environment of the mainframe.

4. Run the following command from the ISPF command line to expand the CNTL data set and create the output dataset for installation:

   TSO RECEIVE INDA('IDF.CNTL.XMIT')
   

5. When prompted to specify restore parameters, enter:

   DA('IDF.CNTL')
   

   Note:

   DA is a parameter of the Restore command. It means Dataset.

6. To expand the LINKLIB dataset, enter the following command from the ISPF command line:

   TSO RECEIVE INDA('IDF.LINKLIB.XMIT')
   

7. When prompted to enter restore parameters, enter:

   DA('IDF.LINKLIB')
   

8. To complete the installation, follow the procedures in IDF.CNTL member #INSTVOY for the Reconciliation Agent, and member #INSTPIO for the Provisioning Agent. For detailed information about these procedures, see #README in the connector installation media.

3.3 Installing the Exits for the Reconciliation Agent

Because the exit modules are in the z/OS Load Library, an IPL may or may not be required to complete the installation. This depends on whether the z/OS Load Library is added to the LinkList, which is a z/OS storage area defined at the time of an IPL. To allow the LDAP Gateway to capture events, the Reconciliation Agent and its exits must be installed on each LPAR that shares the authentication repository.

To install the Reconciliation Agent exits:

1. Ensure that the exits are modules in a LINKLIB, and the SYS1.PARMLIB activates the exits. For example, a typical system would have an entry in OIMACF2.PARMLIB(LPALSTCA).

2. Copy the exits into the appropriate LPAR for the system. Copy the modules IDFACF2E, IDFACF2P, IDFACF2X into CAI.CAILPA. In addition, copy a utility module called IDFCACHE into CAI.CAILPA. The exit modules are in LINKLIB PDS and must be copied to the appropriate LPAR for the system. For detailed information about this step, see the #README in the connector installation media.

3. Modify the control GSO record for system to add the exits. If the GSO record already exists, then change it to activate the exits, or else add a new record. The CA ACF2 exit activation through z/OS is as shown:

   See Also:

   Target system documentation for information about GSO

   READY ,
    
   ACF
    
    ?  SET CONTROL(GSO) SYSID(SYSTEMNAME)
    
    ?  INSERT SYSID(SYSTEMNAME) EXITS LIDPOST(IDFACF2E) EXITS EXPPXIT(IDFACF2X) NEWPXIT(IDFACF2P)
    
    ACF0A026 RECORD ALREADY EXISTS,
    
    ?  CHANGE SYSID(SYSTEMNAME) EXITS LIDPOST(IDFACF2E) EXPPXIT(IDFACF2X) NEWPXIT(IDFACF2P)
    
     SYSTEMNAME / EXITS LAST CHANGED BY MLIGHT ON 03/22/06-23:24,
    
     NEWPXIT(IDFACF2P) EXPPXIT(IDFACF2X) LIDPOST(IDFACF2E)
    
    ? QUIT
   

   Note:

   SYSTEMNAME mentioned in the code is the name of the deployment system.

4. Refresh the GSO to add in the new values by running the following command:

   READY
    
   ACF
    
    ?  F ACF2,REFRESH(EXITS)
    
    ACF79507 GSO PROCESSING COMPLETED WITHOUT ERROR
    
    ?  QUIT
    
    READY
   

5. Perform a re-IPL of the system to the make the exits operational.

To load the exits:

1. APF-authorize the LOADLIB, which contains the installation code. Alternatively, you can run the LINKLST to authorize the LOADLIB. To authorize the LOADLIB manually, run the following command:

   'T PROG=01'
        SYS1.PARMLIB(PROG01)
        APF FORMAT(DYNAMIC)
        APF ADD
                DSNAME(yyyyyyyyyyyyyy)
                VOLUME(xxxxxx)
   

   Where yyyyyyyyyyyyyyyyyyy is the data set name of the installation load library, and xxxxxx is volume serial.

2. To dynamically activate CA ACF2 adapter exits:

   1. Run the following:

      SYS1.PARMLIB(PROG78)
      EXIT ADD EXITNAME(LIDPOST)   MODULE(IDFACF2E)  STATE(ACTIVE)
      EXIT ADD EXITNAME(NEWPXIT)  MODULE(IDFACF2P)  STATE(ACTIVE)
      EXIT ADD EXITNAME(EXPPXIT)   MODULE(IDFACF2X)  STATE(ACTIVE)
      

   2. To activate the exits, set the following value form the z/OS master console:

      T PROG=78
      

3. To dynamically deactivate CA ACF2 adapter exits:

   1. Create a dynamic member as shown:

      SYS1.PARMLIB(PROG79)
      EXIT DELETE ,EXITNAME(LIDPOST), MODULE(IDFACF2E),FORCE=YES
      EXIT DELETE ,EXITNAME(NEWPXIT),MODULE(IDFACF2P),FORCE=YES
      EXIT DELETE, EXITNAME(EXPPXIT) , MODULE(IDFACF2X),FORCE=YES
      

   2. To deactivate the exits, set the following value form the z/OS master console:

      T PROG=79
      

3.4 Configuring the Message Transport Layer

This section describes the following message transport layer configuration tasks for TCP/IP:

Note:

You must configure TCP/IP as the message transport layer protocol. In this section, perform only the steps that are specific to the protocol that you want to use.

• Configuring TCP/IP

• Building and Operation of the Started Tasks

Note:

• Events detected by the Reconciliation Agent through exit technology are transformed into messages and passed to the LDAP Gateway.

• Because TCP/IP is used, the messages are securely sent to the LDAP Gateway.

• If the LDAP Gateway is not running, then messages are held until the Gateway is returned to service and also secured in an AES-encrypted file on the mainframe. The messages are sent when the LDAP Gateway resumes running.

• If the subpool is stopped by an administrator, then it shuts down the Provisioning Agent, thereby destroying any messages that are not transmitted. However, the messages in the AES-encrypted file are not affected and can be recovered.

3.4.1 Configuring TCP/IP

This section describes how to configure TCP/IP as the message transport layer. Check with the systems programmer for detailed information about using TCP/IP. When you configure TCP/IP, the objective is to establish a stateful connection, allowing the pooling of messages and significantly reducing the load on both the mainframe and the LDAP Gateway server.

To establish a TCP/IP connection with the LDAP Gateway:

1. Start the LDAP Gateway.

2. Start the Provisioning Agent started task, which is also preset to establish a TCP/IP connection to the LDAP Gateway on the specified IP address and port number.

3. Start the Reconciliation Agent started task.

To use TCP/IP for the message transport layer, you need the following IP addresses:

• IP address to be used by the mainframe

• IP address for the router

• IP addresses for the domain name servers

Note:

To use TCP/IP as the message transport layer, you might need the help of a systems programmer to create ports on the mainframe and to provide security authorizations.

The Provisioning Agent and Reconciliation Agent JCL shipped with the connector must be edited to specify the user parameters that are specific to the environment. To edit the Provisioning Agent and Reconciliation Agent JCL:

1. Insert an installation-approved job card.

2. Change the value for PARM='TCPN=TCPIP' to the name of the running TCP/IP started task. See the code for batch loading of CA ACF2 user IDs in step 5.

3. Change the IP address to the address of the LPAR from where the Provisioning Agent will be started.

4. Change the port number to the port assigned to the LPAR from where the Provisioning Agent will be started from.

5. If your mainframe installation environment requires batch feeds, then run the required VSAMGETU statement. The following is the code and VSAMGETU statement for batch loading of CA ACF2 user IDs:

   //USR98S01 JOB (,xxxxxxxx,,'PROVISIONING AGENT UPLOAD PROCESS FOR ACIDS'),
   //       'UPLOAD CATS TO XELLTE',
   //       REGION=2M,CLASS=6,MSGCLASS=Q,
   //       USER=ACF2_USER_ID,TIME=1440,
   //       NOTIFY=&SYSUID,TYPRUN=HOLD
   //*
   /*ROUTE PRINT CLE
   //*
   //PIONEERX EXEC PGM=PIONEERX,REGION=0M,TIME=1440,
   //       PARM=('TCPN=TCPIP',
   //       'IPAD=HOST_IP_ADDRESS_OF_ACF2',
   //       'PORT=6500',
   //       'DEBUG=Y')
   //STEPLIB DD DISP=SHR,DSN=PPRD.IDF.LINKLIB
   //     DD DISP=SHR,DSN=SYS2.TCPACCES.V60.LINK
   //     DD DISP=SHR,DSN=TCPIP.SEZATCP
   //SYSOUT  DD SYSOUT=*
   //SYSPRINT DD SYSOUT=*
   //SYSDBOUT DD SYSOUT=*
   //SYSABOUT DD SYSOUT=*
   //ABENDAID DD SYSOUT=*
   //SYSUDUMP DD SYSOUT=*
   //VSAMGETU DD DISP=SHR,DSN=LXT99S.FEEDFILE.SORTED
   //*
   

For the Reconciliation Agent, this is the same with the exception of the PARM card, which is shown here:

//VOYAGERX EXEC PGM=VOYAGERX,REGION=0M,TIME=1440,
//    PARM=('TCPN=TCPIP',
//          'IPAD=&SERVER',
//          'PORT=&PORT',
//          'DEBUG=Y',
//          'ESIZE=16',
//          'DELAY=00',
//          'STARTDELAY=10',
//          'PRTNCODE=SHUTRC')
//STEPLIB  DD DISP=SHR,DSN=IDF.LINKLIB
//         DD DISP=SHR,DSN=TCPIP.SEZATCP
//CACHESAV DD DSN=VOYAGER.CACHESAV,DISP=SHR
//SYSPRINT DD SYSOUT=X
//SYSUDUMP DD SYSOUT=X
//

In these lines of code:

• ESIZE=16 is used to denote AES encryption.

• DELAY is not used for this connector. Do not change the default value (00) of this property.

• STARTDELAY=10 is the recommended value (in seconds).

• PRTNCODE=SHUTRC shows all MVS condition codes after the Reconciliation Agent shuts down. Alternatively, PRTNCODE=TERMRC shows an MVS condition code of 0000 (signifying successful completion) after the Reconciliation Agent shuts down.

  Note:

  To shut down the Reconciliation Agent, run the following command from the z/OS operator's console:

  'F VOYAGER,SHUTDOWN'
  

  To shut down the Provisioning Agent, run the following command from the z/OS operator's console:

  'F PIONEER,SHUTDOWN'
  

• DEBUG can be one of the following for both the Reconciliation Agent and Provisioning Agent:

  • N is for no debugging output.

  • Y is for debugging output.

  • Z is for detailed debugging output.

Note:

If the "data set in use" message is displayed when you attempt to edit a member, then press the F1 key twice to see the member that you are trying to edit. The name of the job that is causing the exception is displayed. On the z/OS console, you can remove the job by using the p or the c command.

Apply the following guidelines while working with the Reconciliation Agent:

• The subpool (RUNSTART.JCL) must be started before starting the Reconciliation Agent. The subpool is used as an in-memory storage for message creation.

• Because you are using TCP/IP, the LDAP Gateway must be started first. If the Reconciliation Agent is started first, then it will throw an error with RETCODE=-01 and ERRORNO=61 because the LDAP Gateway will not be available.

• When the LDAP Gateway is not available, the Reconciliation Agent does not shut down when you run the 'F VOYAGER,SHUTDOWN' command. In this scenario, refer to the following:

  • The following log entry:

    0090  IDMV201I - VOYAGER CONNECTION TO GATEWAY FAILED
    

  • The following error message is generated:

    0090  IEE342I MODIFY   REJECTED-TASK BUSY
    

  When these error messages are generated, you must run CANCEL to force the Reconciliation Agent to shut down.

3.4.2 Building and Operation of the Started Tasks

There are two different JCLs to set up and run the Provisioning Agent and Reconciliation Agent. RUNPIONX and RUNVOYAX are samples to set up the started tasks.

The parameters for RUNPIONX are:

• TCPN: The name of the TCP process

• IPAD: The IP address of the computer on which the Provisioning Agent is running

• PORT: The incoming connection port for the Provisioning Agent

• DEBUG: The debug switch for showing the extra output

• ESIZE: The AES encryption used

The parameters for RUNVOYAX are:

• TCPN: The name of the TCP process

• IPAD: The IP address of the computer on which the Reconciliation Agent is connected

• PORT: The outgoing connection port for the Reconciliation Agent

• DEBUG: The debug switch for showing the extra output

• ESIZE: The AES encryption used

The RUNPIONX and RUNVOYAX are started tasks (STC). The source code for each started task procedure is as follows:

For RUNPIONX:

//ADCDMPPT JOB SYSTEMS,MSGLEVEL=(1,1),MSGCLASS=X,CLASS=A,PRTY=8, 
//  NOTIFY=&SYSUID,REGION=4096K          
//PIONEERX EXEC PGM=PIONEERX,REGION=0M,TIME=1440, 
//  PARM=('TCPN=TCPIP',           
//     'IPAD=&SERVER',  
//     'PORT=&PORT'
//     'DEBUG=Y',              
//     'ESIZE=16',
//     'LPAR=ACF2-SYS')

//    'LPAR= name ')
//STEPLIB DD DISP=SHR,DSN=IDF.LINKLIB       
//     DD DISP=SHR,DSN=TCPIP.SEZATCP
//BATJINFO DD DISP=SHR,DSN=hlq.BATJCARD 
//VSAMGETU DD DISP=SHR ,DSN=hlq.SWUSERS
//VSAMGETO DD DISP=SHR,DSN=hlq.ACF2COUT
//SYSPRINT DD SYSOUT=X                 
//SYSUDUMP DD SYSOUT=X             
//                     

Note:

In the code, hlq stands for installation high-level qualifier.

For RUNVOYAX:

//ADCDMRVX JOB SYSTEMS,MSGLEVEL=(1,1),MSGCLASS=X,CLASS=A,PRTY=8,  
//  NOTIFY=&SYSUID,REGION=4096K          
//VOYAGERX EXEC PGM=VOYAGERX,REGION=0M,TIME=1440,     
//  PARM=('TCPN=TCPIP',                  
//     'IPAD=IP_ADDRESS_OF_ACF2_SYSTEM',  
//     'PORT=5190',
//     'DEBUG=Y')                 
//CACHESAV DD DISP=SHR,DSN=VOYAGER.CACHESAV
//SYSPRINT DD SYSOUT=X               
//SYSUDUMP DD SYSOUT=X             
// 

For the Reconciliation Agent:

The dataset attributes for Cachesav are:

Note:

Cachesav is a data set (file) that is required for Voyager startup. The attributes are the necessary file parameters and must be specified by the administrator performing the installation.

DSORG(PS),LRECL=(32),RECFM=(FB),BLKSIZE=(27968)

The dataset attributes for each of the Pioneer required data sets are:

BATJCARD - DSORG=(PS),LRECL=(80),RECFM=(FB),BLKSIZE=(8000)
VSAMGETU - DSORG=(PS),LRECL=(80),RECFM=(FB),BLKSIZE=(8000)   
VSAMGETO - DSORG=((PS),LRECL=(133),RECFM=(FB),BLKSIZE=(27930)

VSAMGETU needs to be allocated if it is not used.

For the Provisioning Agent:

The BATJCARD data set contents required for ACF2 rule processing, which means adding users to data sets, are as shown:

//QACF0001 JOB SYSTEMS,MSGLEVEL=(1,1),MSGCLASS=X,                      
//     CLASS=A,PRTY=8,NOTIFY=&SYSUID,REGION=4096K,USER=abcdef           
//ACFJOB  EXEC  PGM=IKJEFT01,DYNAMNBR=25                                
//SYSTSPRT DD DISP=SHR,DSN=ADCDM.ACF2COUT                               
//SYSHELP DD DISP=SHR,DSN=SYS1.HELP                                     
//SYSLBC  DD DISP=SHR,DSN=SYS1.BRODCAST                                 
//STEPLIB DD DISP=SHR,DSN=IDF.LINKLIB      

In the second line of code, note user=abcdef. This must be a system level UID with ACF2 privileges to create, modify, and delete users. The SYSTSPRT 'DD' data set name must match the Pioneer 'DD' name in the VSAMGETO 'DD'.