Migrating to a RACF VSAM data set

With z/OS V2R5 and APAR OA62267, you can use a VSAM linear data set as your RACF database if the following conditions are met:

The RACF data set must be at application identity mapping (AIM) stage 3.
The RACF data set should not be defined in MSTRJCL.

Without APAR OA62267, these additional restrictions apply:

The RACF database consists of a single RACF data set.
The VSAM data set is non-SMS managed.
RACF is not in sysplex communications mode or data sharing mode.
The RACF data set is not encrypted.
The RACF data set is not shared with any other system. It can be on a volume, which is defined as shared.

Start of change For more information about restrictions and requirements, see The RACF database. End of change

You must run a series of operations to allocate, populate, and initiate the new RACF® VSAM data set into active status. You can migrate to a RACF VSAM data set with or without an IPL.

Serialization

For requirements, see Serialization of the RACF data set.

Error handling for data set OPEN errors that occur during IPL

If an error occurs during the opening of a RACF data set at IPL, the action that is taken by RACF depends on the following factors:

Enablement of RACF sysplex communications
Initialization order of the systems to be IPLed.

If RACF is not enabled for sysplex communications, the operator is prompted for another RACF data set.

If RACF is enabled for sysplex communications and the system to be IPLed is the first system to enter the sysplex, the operator is prompted for a new RACF data set. If the system to be IPLed is a subsequent system, the system enters RACF permanent failsoft mode.

Using the `PARM=RENAMEACTIVATE` function of IRRUT200

Using the PARM=RENAMEACTIVATE function of IRRUT200 requires that all of the data sets involved in the operation are cataloged in the same catalog that is shared among all systems in the sysplex:

Input active RACF primary data set
Inactive RACF backup data set
Target of the IRRUT200 copy operation.

Considerations for an encrypted data set

Migrating to an encrypted data set is like migrating to a RACF VSAM data set, with the exception that the data set is created as an encrypted data set. Encryption is done by specifying a key label in any of the following ways:

In the DATAKEY field on the DFP segment of the profile that is protecting the RACF VSAM data set.
In JCL (DSKEYLBL keyword) or IDCAMS (DSKEYLABEL keyword)
In an SMS DATACLAS ACS routine

Encrypted RACF data sets use the pervasive encryption services that are provided by VSAM and ICSF. Before you migrate to an encrypted RACF data set, IBM recommends that you first encrypt application data sets. Doing so helps to ensure that CryptoExpress, ICSF, DFSMSdfp, RACF, and your disaster recovery procedures are set up correctly and tested.

RACF data set encryption requires that ICSF is configured to start early as described in "Starting ICSF during IPL-time" in ICSF System Programmer's Guide. Specifically:

The ICSF=xx parameter must be specified in IEASYSxx.
CSFPRMxx must have the cryptographic key data set (CKDS) specified with the CKDSN keyword on all systems that share RACF data sets.

While a complete description of the processing of an encrypted data set is beyond the scope of this publication, diagnosing an encryption issue requires understanding the overall encryption process. For a better understanding of data set encryption, see the following resources:

IBM Redbooks publication Getting Started with z/OS Data Set Encryption, SG24-8410-01.
This publication provides an overview of data protection through encryption and IBM Z pervasive encryption with a focus on IBM z/OS data set encryption. It describes how the various hardware and software components interact in a z/OS data set encryption environment. In addition, this publication focuses on the planning and preparing of the environment and offers implementation, configuration, and operational examples that can be used in z/OS data set encryption environments.
z/OS DFSMS Using Data Sets.
Chapter 5 (“Protecting data sets”) contains the section “Data set encryption,” which describes the hardware, software, and operational requirements to enable data set encryption.

The following points are key to understanding data set encryption:

An encrypted data set must be SMS-managed.
The key label of the ICSF key, which is used to encrypt and decrypt the data set, is set when the data set is created. The key label value is stored in the catalog encryption cell for the data set and is permanently associated with the data set. For information about ICSF setup, see z/OS Cryptographic Services ICSF Administrator's Guide.
The key label can be specified in the following ways:
- By the security administrator in the DFP segment of a data set profile
- At the time of data set creation by using the DSKEYLBL JCL keyword, the DSKEYLBL keyword on the TSO ALLOCATE command, or through the IDCAMS KEYLABEL keyword
- By the storage administrator in the DATACLAS ACS routing for the data set.
After the key label is established for a data set, the data set label remains bound to the data set until the data set is deleted.
The validity of the key object is not validated until the data set is opened.
At the time of the opening of a RACF data set, in addition to an authorization check for the RACF data set, more authorization checks might be performed. These checks are intended to verify that the process that is opening the RACF data set is authorized to the following:
- CSFKRR2 resource in the CSFSERV class
- Key label that is associated with the RACF data set.
RACF data set OPEN operations are subject to these authorization checks, except for OPEN operations that are performed:
- During RACF initialization at IPL
- During RVARY processing, such as an RVARY that is performed by IRRUT200 PARM=ACTIVATE or PARM=RENAMEACTIVATE.

IBM recommends that SMS ACS routines are not used to assign key label for RACF data sets. These labels should be assigned by the security administrator.

Prepare for migration

If the required conditions are met, complete the following action to prepare for migration:

Allocate a new RACF VSAM data set for each database (primary and backup) that you intend to migrate. For more information, see Creating a RACF database.

Migration actions without an IPL

The best time to migrate a RACF data set to a VSAM data set or encrypted VSAM data set is when there is little or no update activity for the RACF data set. RACF administrative work, which includes inbound RRSF work, should be suspended during the time of the copy.

To migrate to a RACF VSAM data set without an IPL, use the following procedure:

Migrate the RACF non-VSAM backup data set to a RACF VSAM data set:
1. Before you start the migration, make backups of your current RACF data sets by using the IRRUT200 utility. For more information, see RACF database verification utility program (IRRUT200).
2. Run the RVARY INACT command to set the backup RACF data set to inactive.
3. Run the IRRUT400 utility with PARM=LOCKINPUT on the primary RACF data set. For an example, see Locking a data set before migration.
4. Use the IRRUT200 utility with PARM=RENAMEACTIVATE(dsn) to copy the primary RACF data set into the VSAM data set previously created; make the RACF VSAM data set your current active backup.
  Note: RENAMEACTIVATE renames the current backup RACF data set name to dsn and renames the RACF VSAM data set to the backup RACF data set name.
  
  For more information about RENAMEACTIVATE, see Copying a RACF database.
5. Run the IRRUT400 utility with PARM=UNLOCKINPUT on the new backup RACF data set.
6. Run the IRRUT400 utility with PARM=UNLOCKINPUT on the primary RACF data set.
After you are comfortable with a RACF VSAM data set as your backup, perform the following steps to exchange the RACF non-VSAM primary data set and RACF VSAM data set:
1. Run the RVARY SWITCH command to exchange the primary data set and the backup data set.
2. Run the RVARY ACTIVE DATASET(dsn) command to make the backup data set active.
  Note: Your primary data set is now the active RACF VSAM backup and your backup data set is now the active RACF non-VSAM primary.
Update your data set name table (ICHRDSNT) or create an IRRPRMxx parmlib member to match this new configuration, in case an IPL is required before you complete this migration.
When you are comfortable with the RACF VSAM data set as your primary, continue with the backup. Repeat Steps 1, 2, and 3 to migrate your current backup (which is essentially your primary) to a VSAM data set.
Note: At the end of this process, your primary and backup are returned to their original configuration.

Locking a data set before migration

You can prevent nonstatistical updates to the RACF data set during the copying process by using the IRRUT400 utility with PARM=LOCKINPUT on the primary RACF data set. When a RACF data set is locked, the data set cannot be updated, except for statistical updates.

Figure 1. Sample JCL for running the IRRUT400 utility with PARM=LOCKINPUT on the primary RACF data set


//IRRUT200 JOB Job card…                                                 
//*------------------------------------------------------------------  
//* SET THE DATA SETS NAMES BELOW:                                     
//*    RACFPRIM= THE CURRENT LIVE ACTIVE RACF PRIMARY DATA SET       
//*    RACFBACI= THE CURRENT LIVE INACTIVE RACF BACKUP  DATA SET       
//*    RACFBACN= THE DATA SET TO BE RENAMED TO BECOME THE NEW LIVE          
//*              RACF BACKUP DATA SET, WHICH MUST BE THE SAME SIZE
//*              AND ON THE SAME TYPE OF DEVICE AS RACFBACI
//*    RACFBACA= THE NAME TO WHICH THE CURRENT LIVE BACKUP ("RACFBACI")
//*              WILL BE RENAMED ("ARCHIVE")   
//*------------------------------------------------------------------  
//            SET RACFPRIM=HLQ.RACFPRIM                        
//            SET RACFBACI=HLQ.RACFBACK                      
//            SET RACFBACN=HLQ.RACFBACK.NEW                      
//            SET RACFBACA=HLQ.RACFBACK.OLD                   
//*------------------------------------------------------------------   
//UT400LOP EXEC PGM=IRRUT400,PARM='LOCKINPUT'                        
//SYSPRINT DD  SYSOUT=*                                                 
//INDD1    DD  DISP=SHR,DSN=&RACFPRIM                                   
//*------------------------------------------------------------------   
//IRRUT200 EXEC PGM=IRRUT200,                                           
//         PARM=RENAMEACTIVATE('&RACFBACA')                             
//SYSPRINT DD  SYSOUT=*                                                 
//SYSRACF  DD  DISP=SHR,DSN=&RACFPRIM                                   
//SYSUT1   DD  DISP=SHR,DSN=&RACFBACN                                   
//SYSUT2   DD  SYSOUT=*                                                
//*------------------------------------------------------------------  
//UT400ULB EXEC PGM=IRRUT400,PARM='UNLOCKINPUT'                     
//SYSPRINT DD  SYSOUT=*                                                
//INDD1    DD  DISP=SHR,DSN=&RACFBACI                                  
//*------------------------------------------------------------------  
//UT400ULP EXEC PGM=IRRUT400,PARM='UNLOCKINPUT'                     
//SYSPRINT DD  SYSOUT=*                                                
//INDD1    DD  DISP=SHR,DSN=&RACFPRIM

Notes:

If you do not run IRRUT400 PARM=UNLOCKINPUT against the current ("'archived") backup data set, it remains locked. This situation is not a problem unless you later try to fall back to the locked backup data set.
The job in Figure 1 ends with return code 4.

Migration actions with an IPL

If the system that uses the RACF data set can tolerate an IPL, you can migrate a non-VSAM RACF data set to a VSAM RACF data set as part of an IPL. To do so, follow these steps:

Create a VSAM data set for the new RACF data set.
Lock the RACF primary data set with IRRUT400 to prevent updates.
Use the IRRUT200 utility to copy the locked RACF data set into the VSAM data set that you created in Step 1.
Use the IRRUT400 utility to unlock the VSAM data set that was populated with the RACF data set contents in the preceding step.
IPL with a data set name table (ICHRDSNT) or IRRPRMxx parmlib member that specifies the new RACF data set.

Start of change It is recommended that you leave the non-VSAM data set in a locked state to prevent updates that would not be reflected in the VSAM data set. End of change

Note: You can perform these steps for the RACF primary data set, RACF backup data set, or both data sets.