Novell Doc: Novell Identity Manager 3.6.1 Driver for Mainframes: RACF Implementation Guide

2.4 Installing the RACF Event Subsystem

An experienced z/OS system programmer familiar with the use of RACF at the local installation should install the RACF Event Subsystem. You should plan about a day to perform the installation tasks. Because the RACF exits reside in LPA, an IPL is required to complete the installation.

To publish RACF events to eDirectory, you must install the RACF Event Subsystem on each system that shares the RACF database.

If you will only subscribe to eDirectory commands, you need only one instance of the RACF Event Subsystem. You do not need to install the RACF exits, you do not need to run the Change Log Started Task, and you do not need a Change Log data set.

The instructions that follow assume that you will install both the Publisher and Subscriber channels.

2.4.1 Setting Up the Libraries on Your z/OS System

The RACF Event Subsystem is packaged as TRANSMIT unloaded z/OS partitioned data sets (PDS).

Samples Library: LDXSAMP.XMT Contains sample cataloged procedures and other JCL.
Load Library: LDXLOAD.XMT Contains executable code.

To prepare the samples library and load library for use:

Use ftp to upload these files to your z/OS system from a PC or file server.
1. FTP your-z/OS-hostname
2. Authenticate to z/OS using your user ID and password.
3. QUOTE SITE LRECL=80 RECFM=FB
4. If you need the files to be stored on a specific disk volume, enter QUOTE SITE VOL= volser
5. BINARY
6. PUT LDXSAMP.XMT
7. PUT LDXLOAD.XMT
8. QUIT
Use RECEIVE to unpack the samples and load library data sets.
1. Log on to z/OS using the same user ID that you used for the ftp session. The names of the files you sent begin with your user ID unless you have changed your TSO profile prefix.
2. Enter RECEIVE INDATASET(LDXSAMP.XMT)
  
  When RECEIVE prompts you for parameters, enter DSNAME(’ hlq.SAMPLIB’) VOLUME( volser) where: hlq.SAMPLIB is the name you want to give the samples library, and volser is the volume where the samples library is to be created.
3. Enter RECEIVE INDATASET(LDXLOAD.XMT)
  
  When RECEIVE prompts you for parameters, enter DSNAME(’ hlq.LDXLOAD’) VOLUME( volser) where: hlq.LDXLOAD is the name you want to give the load library, and volser is the volume where the load library is to be created.
  
  HINT:RECEIVE errors are typically caused by failure to specify BINARY transfer type or LRECL and RECFM parameters when transferring the files to z/OS with ftp.
Add the LDX load library to the APF list.

Use the PARMLIB IEAAPF xx or PROG xx member as appropriate. If you use the dynamic APF facility, you can use the SET PROG command to activate your changes. Otherwise, you must IPL for the change to take effect.
Verify that the load library is APF authorized by entering the following:

D PROG,APF,DSNAME=LDX.LOAD

This should return a listing that includes the load library.
For best practices in security, restrict access to authorized administrator IDs and tasks, such as IDXLOGR and IDXDRVP. Also do not include the library in the linklist.

To verify that the load library is not in the linklist, enter the following:

D PROG,LNKLST

This should return a listing that does not include the load library.

2.4.2 Allocating and Initializing the Change Log Data Set

The Change Log data set is a standard z/OS direct access data set. The Change Log data set must reside on a shared device unless it is used by only a single system.

Create one Change Log data set. It is shared by each z/OS system that shares the RACF database.

The Log File utility LDXUTIL is used to initialize the Change Log data set. The Change Log data set must be initialized before you start the Change Log Started Task for the first time.

To allocate and initialize the Change Log data set:

Customize the samples library member LOGINIT.

Update the JCL to conform to your local installation requirements, and specify
- The name of your LDX load library.
- A name for your Change Log data set.
- The shared disk volume where the Change Log is to be allocated. Specify a different unit name if appropriate.
Run the LOGINIT job.

An IEC031I D37 message is normal and should be ignored.
Ensure that your Change Log data set is given RACF protection appropriate for the sensitive nature of its contents.

WARNING:If you initialize a Change Log data set that contains data, the data is lost.

2.4.3 Setting Up the Change Log Started Task

Copy member LDXLOGRP from the samples library to your started task procedure library (SYS1.PROCLIB or its equivalent). You can give the Change Log Started Task a different name if necessary.
Update the JCL to specify
- The name of your LDX load library
- The name of your Change Log data set
Add the Change Log Started Task to your system startup and shutdown procedures.

For information about starting and stopping the Change Log Started Task, see Starting the Change Log Started Task and Stopping the Change Log Started Task.

The Change Log Started Task should be started during your IPL procedure before user processing begins. Any RACF events of interest that occur are stored in the cross memory queue until the Change Log Started Task has initialized.

The Change Log Started Task should be stopped during your system shutdown procedure after all user processing has ended. Any RACF events of interest that occur after the Change Log Started Task shuts down remain in the cross memory queue and are lost when the system is shut down.
Review your Workload Manager definitions to ensure that the Change Log Started Task is assigned to a Service Class appropriate for its role.

2.4.4 Authorizing the LDXSERV TSO Command

LDXSERV requires APF authorization. LDXSERV resides in the LDX load library, which you added to the APF list in Step 3. You must also add LDXSERV to the list of authorized TSO commands.

To authorize the LDXSERV TSO command:

Add LDXSERV to the AUTHCMD NAMES(...) statement in member IKJTSOxx of SYS1.PARMLIB or its equivalent.

Example:
```
AUTHCMD NAMES( +
  ...other commands... +
  LDXSERV)
```
For more information about IKJTSO xx, see the Initialization and Tuning Reference for your system.
Use the PARMLIB TSO command to activate your changes.

Example:
```
PARMLIB CHECK(00)
PARMLIB UPDATE(00)
```
For more information about the PARMLIB command, see the TSO/E System Programming Command Reference for your system.
Verify that the LDXSERV command is authorized under TSO by entering the following:

PARMLIB LIST(AUTHCMD)

This should return a listing that includes LDXSERV.

NOTE:The LDXISSUE command does not require APF authorization.

2.4.5 Installing the LDXPROC TSO Logon Procedure

The LDXPROC TSO logon procedure provides the environment needed by the driver TSO sessions.

To set up the LDXPROC logon procedure:

Copy member LDXPROC from the samples library to your TSO logon procedure library. You can give the logon procedure a different name if necessary.
Update the JCL to specify the name of your LDX load library on the STEPLIB DD statement.

2.4.6 Creating an Administrative User ID for the Driver TSO Session

The Subscriber channel uses the administrative user ID primarily to issue RACF commands. The Publisher channel uses the administrative user ID primarily to access the Change Log data set.

To set up the administrative user ID:

NOTE:Do this once for each set of systems that share a RACF database.

Define the user with the ADDUSER command.

Specify values for the various parameters as appropriate for your standards. There are no restrictions placed by the driver on the name of the user ID.

The user ID used by the driver must be given the RACF SPECIAL and TSO attributes, and must have no restrictions placed on it that could prevent its intended processing.

Example:
```
ADDUSER LDXUSER DFLTGRP(mygroup) -
 NAME(’RACF DRIVER’) PASSWORD(initial) SPECIAL -
 TSO(PROC(LDXPROC) SIZE(32768))
```
Set the password of the user ID to never expire.

Example:
```
PASSWORD USER(LDXUSER) NOINTERVAL
```
Reset the password of the user ID and mark it not expired. (RACF marks the value specified on the ADDUSER command as being expired.)

Example:
```
ALTUSER LDXUSER NOEXPIRED PASSWORD(xxx)
```

When you set up the Driver object, you specify the user ID and password you create here. For details, see Section 2.6, Setting Up the Driver.

Changing the Password of the Administrative User ID

To change the password of the administrative user ID after installation has been completed:

Use the ALTUSER command as shown in Step 3.
Update the driver configuration with the new Application Password.

For details, see Configuring Driver Parameters after Setup Has Been Completed.

2.4.7 Testing the RACF Event Subsystem before Installing the RACF Exits

You can use the LDXSERV command to test your installation before you install the RACF exits.

To test the RACF Event Subsystem:

If it is not already running, start the Change Log Started Task.

For information about starting the Change Log Started Task, see Starting the Change Log Started Task.
Log on to TSO using the administrative user ID you created for the driver.
Issue this command: LDXSERV STATUS

Examine the output of the command. You should see information about the cross memory queue, information about the Change Log Started Task, and a valid, empty Change Log data set.

For details about interpreting LDXSERV STATUS output, see Output of the LDXSERV STATUS Command.

2.4.8 Installing the RACF Exits

Follow your normal procedure for applying such changes to your z/OS system. We recommend that you

Install and test the exits on a test system or partition first.
Make a copy of your system volumes before applying any changes.
Consider packaging the exits as SMP/E usermods.

To install the RACF exits:

Install LDXEVX01, the Common Command exit, using the Dynamic Exit Facility.

For testing, we recommend that you set up two PROGxx members in SYS1.PARMLIB (or equivalent), to allow for easy removal of the exit if desired.
1. Edit SAMPLIB members PROGAD and PROGDL. Change <LDX load library> to your LDX load library name.
2. Copy these two members to your system PARMLIB data set. If you already have a PROGAD or PROGDL member, rename the LDX members to a PROGxx name that's not in use.
3. When ready, use the console command SET PROG=AD to activate LDXEVX01 as an IRREVX01 exit point.
4. To uninstall the LDX exit, issue SET PROG=DL as a console command.
For permanent installation, do one of the following:
- Add the EXIT ADD statement in PROGAD to your production PROG xx PARMLIB member.
- Add a SET PROG=AD command to CONSOL00 or an automation script, so that it is issued during your IPL procedure.
Install ICHRIX02, the RACROUTE REQUEST=VERIFY(X) (RACINIT) postprocessing exit.
- If you do not have an existing ICHRIX02 exit, run the job in the samples library member RIX0A. This job uses SMP/E to linkedit LDXRIX02 into SYS1.LPALIB as exit ICHRIX02.
- If you have an existing ICHRIX02 exit, update samples library member RIX0B as appropriate. RIX0B installs a router that calls the driver postprocessing exit and your existing exit.
NOTE:To uninstall this exit, use the SMP/E RESTORE function and then IPL with the CLPA option.
After you have installed these two exits, IPL the z/OS system with the CLPA option.

2.4.9 Testing the Completed RACF Event Subsystem Installation

To test the complete RACF Event Subsystem before installing the driver shim:

If it is not already running, start the Change Log Started Task.

For information about starting the Change Log Started Task, see Starting the Change Log Started Task.
Perform some actions to exercise the two RACF exits and create some sample events.
1. Change a password using the logon screen.
2. Create new user ID.
Log on to TSO using the administrative user ID you created for the driver.
Issue this command: LDXSERV STATUS

Examine the output of the command. You should see the RACF exits loaded, information about the cross memory queue, information about the Change Log Started Task, and a valid, non-empty Change Log data set.

For details about interpreting LDXSERV STATUS output, see Output of the LDXSERV STATUS Command.