The RACF report writer

Attention:

The report writer is no longer the recommended utility for processing RACF® audit records. The RACF SMF data unload utility is the preferred reporting utility. The report writer does not support all of the audit records introduced after RACF 1.9.2. See The RACF SMF data unload utility, for more details.

The RACF report writer (RACFRW) uses SMF dates in the form yyddd. If you attempt to select a date range of records with a starting date that occurs before January 1, 2000 (for example, 99364) and the ending date occurs on or after January 1, 2000 (for example, 00002) the report writer will reject your request as it will consider the year 00 as coming before the year 99. Similarly, when sorting records by date, the report writer will treat 00 as coming before 99. IBM® does not intend to enhance the RACF report writer to recognize this condition and to process the records differently, as IBM has stabilized RACFRW and will not make functional improvements to it. Other than this problem with record ordering, which should only occur if the input file has records both before and after January 1, 2000, RACFRW should properly process records with dates after January 1, 2000, if it would have handled those records if they had contained earlier dates.

A successful security mechanism requires that appropriate personnel, particularly the auditor and the security administrator, be able to assess the implementation of the security mechanism and the use of the resources it protects. The RACF report writer provides a wide range of reports that enable you to monitor and verify the use of the system and resources.

The RACF report writer lists the contents of system management facilities (SMF) records in a format that is easy to read. SMF records reside in the SMF data file. You can also tailor the reports to select specific SMF records that contain certain kinds of RACF information. With the RACF report writer, you can obtain:
  • Reports that describe attempts to access a particular RACF-protected resource in terms of user name, user identity, number and type of successful accesses, and number and type of attempted security violations.
  • Reports that describe user and group activity.
  • Reports that summarize system use and resource use.

How the RACF report writer operates

The RACF report writer consists of three phases:
  • Command and subcommand processing
  • Record selection
  • Report generation
See Figure 1 for an overview of the RACF report writer. The figure also shows the replaceable module, ICHRSMFI, for the RACF report writer, and the RACF report writer installation-wide exit, ICHRSMFE.

ICHRSMFI is a nonexecutable module that contains default values for the RACF report writer sort parameters, dynamic-allocation parameters, and processing options. See z/OS Security Server RACF System Programmer's Guide for a description of the contents of the module and an explanation of how to modify the module if necessary.

ICHRSMFE is an installation-wide exit that the RACF report writer calls during the record selection phase. The exit allows you to add functions such as the following to the RACF report writer:
  • Create additional selection and or rejection criteria (or both) for records that the RACF report writer processes
  • Modify naming conventions in records that the RACF report writer processes
  • Add other reports to those that the RACF report writer provides.

Detailed information about coding the ICHRSMFE exit routine appears in z/OS Security Server RACF System Programmer's Guide.

Figure 1. RACF Report Writer Overview
REQTEXT

Phase 1

Command and subcommand processing

The first phase, command and subcommand processing, starts when you enter the TSO command RACFRW or run the report writer as a batch job. As a command, RACFRW invokes the RACF report writer through the terminal monitor program (TMP) and places you in subcommand mode. In subcommand mode, you can enter the RACF report writer subcommands SELECT, EVENT, LIST, SUMMARY, and END. When the RACF report writer is invoked from a batch job, the batch job invokes the TMP through a job step in the JCL, and RACFRW commands and subcommands can be specified as data in stream to the job. See The RACF report writer and the SMF input data set.

Briefly, the SELECT and EVENT subcommands specify which of the input records the RACF report writer selects and uses to generate the reports. You can then produce those reports by using the LIST subcommand to format and print a listing of each SMF record you select and the SUMMARY subcommand to format and print a summary listing of the SMF records. After entering all the subcommands you need, enter the END subcommand. END terminates subcommand mode and the first processing phase.

Note: Pressing PA1 or the attention key at any time during this first phase terminates the RACF report writer immediately and returns control to the TMP.

Phase 2

Record selection

During the second phase, record selection, the RACF report writer compares each record from the input file—the SMF records—against the criteria you specify on the SELECT and EVENT subcommands. The RACF report writer accepts as input only RACF-related SMF records. These are process records (SMF type 20, 30, 80, and 83) and status records (SMF type 81). In addition, the report writer generates a fake type 81 record for every SMF type 80 record that results from a SETROPTS or RVARY command.

For a description of SMF record types 20 and 30, see z/OS MVS System Management Facilities (SMF). For a description of SMF record types 80, 81, and 83, see z/OS Security Server RACF Macros and Interfaces.

Note:
  1. The SMF type 81 record contains “UCB” instead of an EBCDIC device name if the master RACF primary database is on a device with an address greater than X'FFF'. When the RACF report writer formats the type 81 record, this information is displayed for you to see.
  2. The SMF type 83 subtype 1 record is generated when SETROPTS MLACTIVE is in effect and a RACF command (ALTDSD, ADDSD, DELDSD) has changed the security label in a profile. The record contains the names of the cataloged data sets affected by the security-label change. A link value is contained in both the SMF type 80 record for the RACF command and the SMF type 83 subtype 1 record. The link value is used to connect the list of data set names affected by the security-label change with the RACF command that caused the change. The text in the report-writer output is LINK=numeric value.

    If there are migrated items in the list, and the migration facility is unavailable at the time the command is issued, the following messages will be printed after the items:

       ** Unable to verify this
       ** migrated item.(1)

    The number in parentheses denotes diagnostic information used by IBM support.

    For more information about using the LISTDSD command, see z/OS Security Server RACF Command Language Reference.

If you do not specify any SELECT or EVENT subcommands, the RACF report writer selects all of the records from the input file for further processing. If you specify options that limit your report, only limited information is saved.

Record reformatting

To sort and print the SMF input records, the RACF report writer must reformat them. The report writer allocates an in-storage buffer for reformatting, using it on each SMF record being processed. The size of this buffer is determined by the WRKLRECL field in the installation-replaceable module ICHRSMFI unless LRECL is specified on SORTIN DD. The LRECL value in the SORTIN DD statement overrides the WRKLRECL statement used by RACFRW.

The report writer makes sure that the buffer is large enough for the base section of the SMF record. However, it does not guarantee that the relocate sections of the SMF record will fit.

In the report writer output, the process records that do not fit into the buffer are noted as truncated. The status records that do not fit will be noted as bypassed. The WRKLRECL default is 4096.

The RACF report writer copies the reformatted records to a work data set. You can save this work data set and use the reformatted records as input to a later run of the RACF report writer.

If the input consists of records previously saved using the report writer, those records are already reformatted. The RACF report writer skips the reformatting step for those records. Operands on the RACFRW command specify whether the RACF report writer is to reformat the input records and whether the work data set is to be saved for subsequent runs of the RACF report writer.

When the RACF report writer has compared all the input records against the selection criteria and, if necessary, has reformatted the selected records and copied them to a work data set the second processing phase is complete.

Phase 3

Report generation

During the third phase, report generation, the RACF report writer generates the reports that you request with the LIST and SUMMARY subcommands. It uses as input only the records from the work data set The RACF report writer always produces a header page with a list of the subcommands that you have entered and describes the meanings of values for such activities as job initiation, TSO logon, resource access, and use of RACF commands that appear in the reports. The other reports depend on operands you have specified, but the RACF report writer always produces the reports you request according to a specific order. See the examples at the end of this section.

If you want a general summary report of overall system activity related to RACF, you can specify the GENSUM operand on the RACFRW command. The RACF report writer:

  1. Collects the data for the general summary report during the record selection phase (see Phase 2) and prints it before any other reports during phase 3.
  2. Produces reports for the LIST subcommand and lists all SMF records from the work data set in the sequence that you specified.
  3. Produces a separate summary report of the SMF records for each SUMMARY subcommand you enter with a RACFRW command. Depending on the subcommand you enter, the report contains records by group, resource, command, RACF event, or owner activity.

Sample reports produced by GENSUM, LIST, and SUMMARY are shown in the section Sample reports. When it has completed the last report, the RACF report writer terminates and returns control to the TMP.

RACF report writer command and subcommands

The following tables summarize the main RACFRW command operands and subcommands that control report writer processing:

Table 1. Summary of RACFRW Command and Its Operands
Operand Result
GENSUM Produces a general summary report of system activity related to RACF
NOGENSUM Produces no general summary report
FORMAT Specifies that SMF records are to be formatted for use by the report writer
NOFORMAT Specifies that the input SMF records are already formatted for use by the report writer; no reformatting is necessary
SAVE Saves the reformatted records on a work data set. Only those records that satisfy the specified SELECT/EVENT criteria are saved
Table 2. Summary of RACFRW Subcommands
Subcommand Result
SELECT Specifies which SMF records to choose from the input file for report writer processing
EVENT Specifies further which SMF records to choose from the input file; for the report writer to process these records, each record must meet the criteria
LIST Specifies that the report writer is to list each record that is processed by SELECT/EVENT groups
SUMMARY Specifies that the report writer is to print summary reports for records processed by SELECT/EVENT groups
END Terminates subcommand processing

Planning considerations

To use the RACF report writer at your installation, you must have:
  • The DFSORT IBM Program Product (Program Number 5740-SM1), or equivalent.
  • An output device that can handle 133 character lines.

The RACF report writer and the SMF input data set

The input data set to the RACF report writer consists of the following SMF record types:
20
Job initiation
30
Common address work data
80
RACF processing
81
RACF initialization
83
RACF processing
Attention:

Even though some commands use the relocate 44 section of the record, the output of these records is not consistent. The RACF SMF data unload utility is the preferred reporting utility.

SMF records

Records from the SMF data set or log stream must first be dumped to a data set that RACF can use as input. If you have access to the SMF data set or log stream, you can use the SMF dump program (IFASMFDP or IFASMFDL) to dump the SMF records. (If your installation does not allow you to access the SMF data set or log stream, see your SMF system programmer to find out how you can obtain the SMF records as input to the RACF report writer.)

Running the report writer as a batch job

For large SMF data sets, you should run the report writer as part of a batch job. The following JCL is an example of how to dump the SMF records to a temporary data set and run the report writer as a batch job.

In Figure 2, the SMF dump program IFASMFDP dumps record types 20, 30, 80, 81, and 83 from an SMF data set (SYS1.MANA) to a temporary data set (QSAMOUT DD) for use by the report writer.

Figure 2. JCL for Dumping SMF Records and Running the Report Writer as a Batch Job
/*****************************************************************
/*****************************************************************
/*                                                               *
/*              RUN THE SMF DUMP PROGRAM.                        *
/*                                                               *
/*****************************************************************
/*****************************************************************
//SMFDUMP  EXEC PGM=IFASMFDP
//SYSPRINT DD SYSOUT=*
//VSAMIN   DD DSN=SYS1.MANA,DISP=SHR
//QSAMOUT  DD DSN=&&QSAMOUT,DISP=(NEW,PASS,DELETE),
//         SPACE=(TRK,(25,50),RLSE),UNIT=SYSALLDA
//SYSIN    DD *
           INDD(VSAMIN,OPTIONS(DUMP))
           OUTDD(QSAMOUT,TYPE(020,030,080,081,083))
           DATE(89195,89195)
           SID(MVS1)
           SID(MVS3)
/*****************************************************************
/*****************************************************************
/*                                                               *
/*              RUN THE RACF REPORT WRITER AS A BATCH JOB        *
/*              AND USE SMF DATA FROM QSAMOUT.                   *
/*                                                               *
/*****************************************************************
/*****************************************************************
//RACFRW2  EXEC PGM=IKJEFT01
//SORTWKxx DD your sort work files
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//RSMFIN   DD DISP=(SHR,PASS,DELETE),DSN=*.SMFDUMP.QSAMOUT
//SYSTSIN  DD *,DLM=XX
           RACFRW TITLE('RACF REPORTS') GENSUM
           SELECT VIOLATIONS
           LIST TITLE('ACCESS VIOLATIONS SUMMARY REPORT')
           SUMMARY RESOURCE BY(USER)
           END
XX

You can specify options for IFASMFDP on the SYSIN INDD statement, and the selection criteria for the SMF records on the SYSIN OUTDD statement. You can also specify the start and end date for the dump program in Julian format (YYDDD) on SYSIN DATE and the system identification on SYSIN SID.

For more information about IFASMFDP and the SMF dump options, including outputting log stream output using IFASMFDL, see z/OS MVS System Management Facilities (SMF).

RACFRW then uses the temporary data set QSAMOUT as input defined on the RSMFIN DD statement, and you can specify the report-writer command and subcommands as in-stream data to SYSTSIN DD.

Running the report writer using the RACFRW command

You can also run the RACF report writer as a TSO command. In TSO ready mode enter RACFRW. RACF places you in subcommand mode, and you can enter the report writer subcommands (SELECT, EVENT, LIST, SUMMARY, and END).

If you run the report writer as a TSO command, you must pre-allocate the data set that contains the selected SMF records as RSMFIN and use it as input to the report writer command and subcommands. See Pre-allocating data sets for more information about pre-allocating data sets for the report writer.

Pre-allocating data sets

If you run the report writer as a TSO command, pre-allocate the data sets required by the RACF report writer using the following ddnames:
RSMFIN
The input data set or sets. Note, however, that if you enter the DATASET operand on the RACFRW command, the RACF report writer assigns a system-generated DD name to this input data set and ignores RSMFIN. If you neither pre-allocate the input data set nor specify the DATASET operand, the RACF report writer issues message ICH64305I, and terminates immediately.
SYSPRINT
The output data set. If you do not pre-allocate this output data set, the RACF report writer allocates this data set to a SYSOUT data set (which goes to the terminal on which you are entering the commands and subcommands).
SORTIN
The work data set. If you enter the SAVE operand on the RACFRW command, the RACF report writer assigns SORTIN to the work data set that you specify in the SAVE operand. If you pre-allocate the work data set or specify the SAVE operand, the RACF report writer saves this work data set for future use; otherwise, it allocates the work data set to a temporary data set and deletes it at job termination. See the SAVE and FORMAT/NOFORMAT options described in RACFRW command.

If the logical record length is specified, it overrides the WRKLRECL field in the installation-replaceable ICHRSMFI module. The default value of WRKLRECL is 4096. If the logical record length you specify is not large enough to hold the largest SMF record from RSMFIN, the report writer truncates the record, losing some of the information for the record's output.

SORTLIB
The system library that contains the SORT/MERGE load modules. If you do not pre-allocate this system library, the RACF report writer allocates it to the sort data set named in SORTDSN in ICHRSMFI. Initially, the name in SORTDSN is SYS1.SORTLIB.
SORTDDNM
The SORT/MERGE messages. The RACF report writer allocates these messages to the data set named in SORTDDNM in ICHRSMFI. If you do not pre-allocate these messages, they go to the terminal on which you are entering the commands and subcommands, because the initial name in SORTDDNM is SYSOUT.
SORTWKxx
The SORT/MERGE work file(s), named SORTWK01 to SORTWKnn. If you do not pre-allocate these files, dynamic allocation occurs, using the dynamic allocation parameter specified in SORTDYN in ICHRSMFI. Initially, SORTDYN contains ‘DYNALLOC=3350’.

Note that any data set that you pre-allocate remains allocated after the RACF report writer terminates, while any data set allocated by the RACF report writer is deallocated before termination.

RACF report writer return codes

After completing, the RACF report writer returns control to the terminal monitor program (TMP) with a return code in register 15.

The following are possible return codes:
Return Code
Meaning
0
The report writer has terminated normally.
12
The report writer has not terminated successfully for one of the following reasons:
  • It could not dynamically allocate any needed resource that was not pre-allocated by the user
  • It could not open any needed resource
  • It received a nonzero return code from a service routine that it has invoked
  • It received a nonzero return code from the SORT/MERGE routines.
If you receive a return code of 12, check to see whether any error messages were issued when you invoked the report writer.
  • If you receive a return code of 12 when the report writer is running in batch, check that the job statement in the JCL specifies MSGLEVEL=(1,1).
  • If you receive a return code of 12 when you invoke the report writer from a TSO terminal, make sure the following option is included in your user profile:
    profile wtpmsg msgid

For more information about report writer error messages, see z/OS Security Server RACF Messages and Codes.

Useful hints

When you use the RACF report writer, consider the following:
  • You must use the SMF dump program, IFASMFDP, to dump the SMF data set, which is a VSAM data set, into a QSAM data set, which is what the RACF report writer requires. For additional information about IFASMFDP, see z/OS MVS System Management Facilities (SMF).
  • In an installation using RACF to protect multiple systems, each system writes RACF-generated SMF records to a different data set. You can concatenate all of these data sets into a single data set for input to the RACF report writer. Later, should you have to separate the information based on the identifier of the system that generated it, you could use the SYSID operand on either the LIST or the SELECT subcommand.
  • By using the SELECT and EVENT subcommands, you can retrieve individual SMF records of interest for display at a TSO terminal (display screen).
  • If your SMF file is large or resides on multiple tape volumes, you may consider specifying the SAVE operand for the work data set that you create. This action reduces the amount of time and number of devices you need, should you need to use this work data set again to produce additional reports. Note that by using SELECT and EVENT subcommands, you can create and save a subset of a work data set that you saved in a previous run of the RACF report writer.
  • Your system programmer can provide special SMF record selection and tailoring by using the RACF report-writer exit routine ICHRSMFE. For more information, see z/OS Security Server RACF System Programmer's Guide.
  • The RACF report writer runs as a postprocessor of RACF and does not interfere with normal RACF processing.

RACFRW command

This section shows the function and syntax of the RACF report writer command (RACFRW) and subcommands (SELECT, EVENT, LIST, SUMMARY, and END). The command and subcommands are not listed alphabetically, but in the order in which you are likely to enter them. This order is: RACFRW, SELECT, EVENT, LIST, SUMMARY, and END.

The following key defines the symbols used to represent the syntax of the command and subcommands:

UPPERCASE
characters must appear as shown
lowercase
characters indicate that the user supplies the information
list...
indicates that the item can be listed more than once
{ }
group alternative items; you can only specify one item
[ ]
indicates an optional item that you can specify
KEYWORD
indicates the default when no item is specified

The TSO command RACFRW invokes the RACF report writer. After you enter the RACFRW command, TSO places you in subcommand mode and prompts you to enter the RACF report-writer subcommands until you enter the END subcommand.

On the RACFRW command, you can specify the source and disposition of input records, the data to be passed to the installation-wide exit routine (ICHRSMFE), whether the RACF report writer is to reformat the input records, and whether the RACF report writer is to print a general summary report. (See z/OS Security Server RACF System Programmer's Guide for further information about the installation-wide exit ICHRSMFE.)

The Syntax of the RACFRW Command:

RACFRW        [TITLE('q-string')]

              [DATA('q-string')]

              [{FORMAT  }]
              [{NOFORMAT}]

              [{DSNAME }] (name-list...)
              [{DATASET}]

              [SAVE(name)]

              [LINECNT( {  60  } ) ]
              [         {number}   ]

              [{GENSUM  }]
              [{NOGENSUM}]
TITLE(‘q-string’)
specifies a string of up to 132 characters, enclosed in single quotation marks, to be used as a default heading for the report pages, if the TITLE operand on either the SUMMARY or LIST subcommand does not specify a unique report heading for a requested report.
DATA(‘q-string’)
specifies a string of up to 256 characters of data, enclosed in single quotation marks, to be passed to the installation-wide exit routine (ICHRSMFE).
FORMAT
specifies that the RACF SMF records used as input to the RACF report writer must be reformatted (from the way they appear in the SMF records) before processing. For additional information about the reformatted records, see z/OS Security Server RACF System Programmer's Guide. FORMAT implies that the RACF report writer has not previously processed the input records. FORMAT is the default value.
NOFORMAT
specifies that the RACF SMF records used as input to the RACF report writer are already reformatted and suitable for processing. NOFORMAT implies that the input records have been processed previously by the RACF report writer and saved. You can save input records by specifying the SAVE operand.
Note: Specifying FORMAT for a data set that is already reformatted or specifying NOFORMAT for a data set that is not already reformatted can cause unpredictable results.

If report-writer input is from SMF, records are not reformatted. If input is a file saved from a previous report-writer run, records are reformatted.

Restriction:

If records have been reformatted and saved using the SAVE operand on one release of RACF report writer, the same release must be used to process the saved reformatted records. For example, RACF 1.9 reformatted records must be processed with RACF 1.9. SMF records from previous RACF releases, however, are supported. If you want to process SMF data from previous releases, archive the original SMF records rather than the reformatted records.

DSNAME(name-list...) or DATASET(name-list...)
specifies the name of one or more cataloged data sets to be concatenated and used as input to the RACF report writer. If you omit this operand, the RACF report writer uses as input the data set you have pre-allocated to the RSMFIN DD name. For more information about preallocating RSMFIN, see Pre-allocating data sets.
SAVE(name)
specifies the name of a sequential data set to be assigned to the work data set that is to contain the selected, reformatted RACF SMF records. If this ‘name’ data set is new, the RACF report writer allocates and catalogs it. If this ‘name’ data set is old, the RACF report writer replaces the data currently in the data set with the new data and keeps the data set. You can use this saved work-data set as input to a later run of the RACF report writer.

If you omit this operand and have not pre-allocated a SORTIN DD name, the work-data set is deleted at job termination.

LINECNT(number)
specifies the maximum number of lines to be written before ejecting to a new page. The minimum number that you can specify is 20. If you specify a number lower than 20, LINECNT defaults to 20. If you omit this operand, LINECNT defaults to 60.
GENSUM
specifies that a general summary report is to be printed. This report contains various statistics about all the RACF SMF records processed, such as total JOB/LOGON attempts, successes, and violations, total resource accesses, successes, and violations, and a breakdown of JOB/LOGON and resource access violations by hour.
NOGENSUM
specifies that a general summary report is not to be printed. NOGENSUM is the default value.

RACFRW subcommands

When you invoke RACFRW as a TSO command, you are placed in subcommand mode. You can then enter subcommands to select the records and the format for the reports.

SELECT subcommand

The SELECT subcommand allows you to choose specific records from the input file containing the RACF SMF records. The RACF report writer reformats these selected records, if necessary, and copies them to an MVS™ work-data set. Although all input records are used for the general summary report, the RACF report writer can list and generate summary reports for only the records that are indicated on the SELECT subcommand. The SELECT subcommand determines which records get processed.

Note: RACF reports are only as good as the SMF records used as input to them. You need to carefully consider your installation's needs when selecting audit options and be sure the report writer has enough data to make useful reports.

SELECT/EVENT groups

SELECT and EVENT subcommands provide a way to tailor RACF report-writer output. It is easier for you to review a few, selected reports than to examine all the data at once. SELECT and EVENT commands work together to restrict the SMF records that the report writer uses for input. You can run the report writer several times on the same SMF data using different SELECT and EVENT criteria to obtain several reports on specific topics. You can issue SELECT subcommand separately or with EVENT subcommands to form what is called a SELECT/EVENT group.

For each run of the report writer, you can specify zero or more SELECT/EVENT groups. Each group consists of a SELECT subcommand followed by zero or more EVENT subcommands. A second SELECT subcommand indicates the beginning of another group.

For an SMF record to be used in a RACF report, it must meet the criteria of at least one of the SELECT/EVENT groups. The SMF record must meet all the criteria of the SELECT subcommand plus all the criteria of at least one of the EVENT subcommands in that group.

A SELECT/EVENT group must begin with a SELECT subcommand, even if it is a SELECT subcommand with no operands. You can then follow this subcommand with up to 49 EVENT subcommands that specify additional selection criteria for that group. If you do not specify an EVENT subcommand, RACF uses only the criteria from the SELECT subcommand. See EVENT subcommand for more information.

If you specify multiple SELECT subcommands or SELECT/EVENT groups or both, you can specify the groups in any order. The listing and summary reports that you request, however, will reflect all the records that have been selected by all the groups, not just the records selected by one particular SELECT/EVENT group. If you do not issue any SELECT subcommands or SELECT/EVENT groups, all the RACF SMF records from the input file are selected.

The RACF report writer can process a maximum of 50 SELECT and EVENT subcommands. If you enter more than 50, TSO accepts only the first 50, then prompts you to enter a subcommand other than SELECT or EVENT.

The following example produces a listing of all unsuccessful logons and all successful SETROPTS commands.
RACFRW
SELECT VIOLATIONS
EVENT LOGON
SELECT SUCCESSES
EVENT SETROPTS
LIST
END
The next example provides a listing of every unsuccessful RACF event (logons, accesses, SVCs, commands) plus successful logons and successful SETROPTS commands.
RACFRW
SELECT VIOLATIONS
SELECT SUCCESSES
EVENT LOGON
EVENT SETROPTS
LIST
END
The following example results in a listing of every RACF-related SMF record.
RACFRW
LIST
END
Note: Use a comma to separate items in a list of operands for SELECT or EVENT. If you must continue items in a list on another line, use the standard TSO continuation, as in the following example:
SELECT  DATE(89195:89197)  TIME(010000:120000) USER(user1,user2,+
user3,user4,user5)

See the syntax of the SELECT and EVENT subcommands for those operands that allow you to specify lists of items.

The syntax of the SELECT subcommand:

{SELECT}   [DATE  {(begin-number:end-number)} ]
{SEL   }   [      {(number-list...)         } ]

           [TIME  {(begin-number:end-number)} ]
           [      {(number-list...)         } ]

           [{VIOLATIONS}]
           [{SUCCESSES }]
           [{WARNINGS  }]

           [{USER(name-list...)}]
           [{NOUSER            }]

           [{JOB(name-list...)}]
           [{NOJOB            }]

           [{OWNER(name-list...)}]
           [{NOOWNER            }]

           [GROUP(name-list...)]

           [STEP(name-list...)]

           [{STATUS}]
           [{PROCESS}]

           [SYSID(value-list...)]

           [ AUTHORITY( [NORMAL] [SPECIAL]     ]
           [            [OPERATIONS] [AUDITOR] ]
           [            [EXIT] [FAILSOFT]      ]
           [            [BYPASSED] [TRUSTED])  ]

           [ REASON( [CLASS] [USER] [SPECIAL]      ]
           [         [RESOURCE] [RACINIT]          ]
           [         [COMMAND] [CMDVIOL] [AUDITOR] ]
           [         [SECAUDIT] [VMAUDIT]      ]
           [         [SECLABELAUDIT] [LOGOPTIONS]  ]
           [         [COMPATMODE] [APPLAUDIT]) ]

           [TERMINAL(name-list...)]
DATE(begin-number:end-number) or DATE(number-list...)
specifies a range (in ascending order) or a list of dates in the form YYDDD that are to be selected for further processing.
TIME(begin-number:end-number) or TIME(number-list...)
specifies a range (in ascending order) or a list of times in the form HHMMSS that are to be selected for further processing.
VIOLATIONS
specifies that only records identifying security violations are to be selected for further processing. This field applies to PROCESS records only.
SUCCESSES
specifies that only records identifying successful access attempts are to be selected for further processing. SUCCESSES applies to PROCESS records only.
WARNINGS
specifies that only records for which a warning message was issued are to be selected for further processing. This field applies to PROCESS records only.

If you do not specify VIOLATIONS, SUCCESSES, or WARNINGS, none of these is used as a selection criterion.

USER(name-list...)
specifies a list of user IDs that are to be selected for further processing. USER applies to PROCESS records only. If you omit both the USER and NOUSER operands, the RACF report writer selects all records containing user IDs. (See Notes 1 and 2.)
NOUSER
specifies that:
  • Records containing user IDs are not to be selected for further processing
  • Records containing undefined users are selected. You can use the list to define those user IDs if you want.

If you omit both the USER and NOUSER operands, the RACF report writer selects all records containing user IDs. If you specify both the NOUSER and NOJOB operands, the RACF report writer ignores both operands. (See Notes 1 and 2.)

JOB(name-list...)
specifies a list of job names that are to be selected for further processing. JOB applies to PROCESS records only. If you omit both the JOB and NOJOB operands, the RACF report writer selects all records containing job names. (See Note 1.)
NOJOB
specifies that records that contain job names are not to be selected for further processing. If you omit both the JOB and NOJOB operands, the RACF report writer selects all records containing job names. If you specify both the NOUSER and NOJOB operands, the RACF report writer ignores both operands. (See Note 1.)
OWNER(name-list...)
specifies a list of resource owner names that are to be selected for further processing. OWNER applies to PROCESS records only. If you omit both the OWNER and NOOWNER operands, owner is not a selection criterion.
NOOWNER
specifies that records that contain resource owner names are not to be selected for further processing. If you omit both the OWNER and NOOWNER operands, owner is not a selection criterion.
GROUP(name-list...)
specifies a list of group names that are to be selected for further processing. GROUP applies to PROCESS records only. (See Note 1.)
STEP(name-list...)
specifies a list of step names that are to be selected for further processing. STEP applies to PROCESS records only. (See Note 1.)
STATUS
specifies that only STATUS records are to be selected for further processing. STATUS records are RACF SMF record types 80 (generated by the SETROPTS or RVARY command) and 81.
PROCESS
specifies that only SMF record types 20, 30, 80, and 83 are to be selected for further processing.
SYSID(value-list...)
specifies a list of system identifiers that are to be selected for further processing.
AUTHORITY(type...)
specifies a list of authority types that are to be selected for further processing. AUTHORITY applies to PROCESS records only. Type can be any of the following:
SPECIAL
Selects records produced because the user had the SPECIAL or group-SPECIAL attribute
OPERATIONS
Selects records produced when access was granted because the user had the OPERATIONS or group-OPERATIONS attribute
AUDITOR
Selects records produced because the user had the AUDITOR or group-AUDITOR attribute
EXIT
Selects records produced when access was granted by an installation-wide exit routine
NORMAL
Selects records produced when access was granted for a reason other than those already listed (for example, when the user had sufficient access authority)
FAILSOFT
Selects records produced when failsoft processing was in effect
BYPASSED
Selects records produced because of accesses in which RACF authority checking was bypassed because BYPASS was specified on the user ID
TRUSTED
Selects records produced when access was granted because the user had the trusted attribute.
REASON(value...)
specifies the reasons for logging the records that are to be selected for further processing. The REASON operand applies to PROCESS records only. Its value can be any of the following:
CLASS
Selects records produced because auditing of profile changes was in effect for a particular class. This record was produced because SETROPTS AUDIT was in effect.
USER
Selects records produced because auditing was in effect for the specific users. This record was produced because UAUDIT was specified for the user.
SPECIAL
Selects records produced because:
  • SETROPTS SAUDIT is in effect, which produces records for RACF commands requiring SPECIAL or group-SPECIAL authority.
  • SETROPTS OPERAUDIT is in effect, which produces records for resource accesses requiring OPERATIONS or group-OPERATIONS authority.

If both SAUDIT and OPERAUDIT are in effect, records for both are selected. If neither one is in effect, no records are selected.

RESOURCE
Selects records produced because auditing was in effect for the specific resource or because a RACHECK installation-wide exit routine requested auditing. (See Note 3.)
RACINIT
Selects records produced by a RACINIT request.
COMMAND
Selects records produced by commands that are always logged.
CMDVIOL
Selects records produced because auditing of command violations was in effect. This record was produced because SETROPTS CMDVIOL was in effect.
AUDITOR
Selects records produced because auditing of the specific resource was in effect. This record was produced because GLOBALAUDIT was specified in the profile. (See Note 3.)
SECAUDIT
Selects records produced because auditing of resources according to SECLEVEL was in effect. This record was produced because SETROPTS SECLEVELAUDIT was in effect.
VMAUDIT
Selects records produced because auditing of specific z/VM® events was in effect. This record has meaning only if you are sharing a database with a z/VM system.
SECLABELAUDIT
Selects records produced because auditing of resources according to security label was in effect.
LOGOPTIONS
Selects records produced because LOGOPTIONS auditing was in effect for a particular class.
COMPATMODE
Selects records produced because SETROPTS COMPATMODE was in effect.
APPLAUDIT
Selects records produced because SETROPTS APPLAUDIT was in effect.
TERMINAL(name-list...)
specifies a list of terminal IDs that are to be selected for further processing. TERMINAL applies to PROCESS records only.
Note:
  1. Users who are not defined to RACF do not have a RACF user ID. Furthermore, they cannot connect to RACF. For this reason, the RACF SMF records associated with these MVS users contain the job name in place of the user ID and the step name in place of the group name.
    Specifying SELECT USER(USERA) selects records for USERA including all records that have a job name in place of a user ID. If you want only records for USERA, specify:
    SELECT  USER(USERA)  NOJOB
    Similarly, specifying SELECT GROUP(GROUPA) selects records for GROUPA, including records that have a step name in place of a group name. If you want only records for GROUPA, specify:
    SELECT  GROUP(GROUPA)  STEP(any-name)
    There is no NOSTEP parameter.
  2. If the user name is available in the relocate section of SMF record type 80, RACF includes it in both the PROCESS records listing and the SUMMARY reports.
  3. The RACF report writer can select a record because of either RESOURCE or AUDITOR or both RESOURCE and AUDITOR.

EVENT subcommand

The EVENT subcommand allows you to specify selection criteria related to particular RACF events. For a record to be selected for further processing by the RACF report writer, it must satisfy all the selection criteria that you specify on this EVENT subcommand.

You can use the EVENT subcommand only with a SELECT subcommand in a SELECT/EVENT group. With the EVENT subcommand, you can create a subset of the records that have already met the selection criteria specified on the SELECT subcommand. (SELECT subcommand describes SELECT/EVENT groups in more detail.)

The EVENT subcommand applies to PROCESS records only.

Keep in mind that the report is compiled by the number of records processed, which is determined by the SELECT subcommand, not just the records listed, which is determined by the EVENT subcommand. Therefore, it is possible for a report to have record totals in it that do not match the number of records for which you have set the criteria. The report totals list all the records that it processed in creating the report.

The syntax of the EVENT subcommand:

{EVENT}          event-name
{EV   }

                 [EVQUAL(value-list...)]

                 [CLASS(name-list...)]

                 [NAME(name-list...)]

                 [DSQUAL(name-list...)]

                 [INTENT( [ALTER] [CONTROL] [UPDATE] ]
                 [        [READ]   [NONE] )          ]

                 [ALLOWED( [ALTER] [CONTROL] [UPDATE] ]
                 [         [READ]  [NONE] )           ]

                 [NEWNAME(name-list...)]

                 [NEWDSQUAL(name-list...)]

                 [        {begin-number:end-number}   ]
                 [ LEVEL( {                       } ) ]
                 [        {number-list...         }   ]
event-name
specifies one of the following valid event names:
LOGON
TSO logon or batch job initiation
ACCESS
Access to a RACF-protected resource
ADDVOL
Add a volume to a multivolume data set or tape volume set
RENAME
Rename a data set, SFS file, or SFS directory
DELETE
Delete a resource
DELVOL
Delete one volume of a multivolume data set or tape volume set
DEFINE
Define a resource
ALLSVC
All of the preceding functions (ACCESS, ADDVOL, RENAME, DELETE, DELVOL, and DEFINE)
ADDSD
ADDSD command
ADDGROUP
ADDGROUP command
ADDUSER
ADDUSER command
ALTDSD
ALTDSD command
ALTGROUP
ALTGROUP command
ALTUSER
ALTUSER command
CONNECT
CONNECT command
DELDSD
DELDSD command
DELGROUP
DELGROUP command
DELUSER
DELUSER command
PASSWORD
PASSWORD command
PERMIT
PERMIT command
RALTER
RALTER command
RDEFINE
RDEFINE command
RDELETE
RDELETE command
REMOVE
REMOVE command
RVARY
RVARY command
SETROPTS
SETROPTS command
ALLCOMMAND
All of the preceding RACF commands (ADDSD through SETROPTS)
APPCLU
Partner LU verification through use of APPCLU profile.
GENERAL
General purpose auditing
Not all of the EVENT subcommand operands are valid with certain event names.
EVQUAL(value-list...)
specifies a list of event qualifiers to be selected.
CLASS(class-name...)
specifies a list of resource class names to be selected. Only the DATASET class and class names found in the class descriptor table are valid.
NAME(name-list...)
specifies a list of resource names to be selected. In the NAME field, you must specify a fully qualified data set name, not a profile name for RACF SVC events (ACCESS, ADDVOL, RENAME, DELETE, DELVOL, DEFINE, ALLSVC). However, you must specify a profile name, not a fully qualified data set name, in the NAME field for RACF command events (ADDSD, ALTDSD, DELDSD, PERMIT, RALTER, RDEFINE, RDELETE, ALLCOMMAND).

To select specific data sets, you must specify fully qualified dataset names in the ‘name-list’. Also, if a dataset has been renamed and you want to use this operand to select the old dataset name, you must specify the fully qualified, old data set name in the ‘name-list’. This operand is not valid with the LOGON event name. You can specify generic names if you are looking for commands issued against that profile.

DSQUAL(name-list...)
specifies a list of dataset qualifiers to be selected. Valid dataset qualifiers are any user IDs or group names used as the high-level qualifier of a dataset name or any qualifiers supplied by the ICHRSMFE installation-wide exit routine. If a data set has been renamed and you want to use this operand to select the old dataset name, you must specify the qualifier of the old dataset name in the ‘name-list’.

To obtain records that are pertinent solely to the dataset class, you must also specify CLASS(DATASET); otherwise, you receive records for all valid classes.

INTENT
specifies a list of intended access authorities to be selected. An intended access authority is the minimum authority needed by a user to access a particular resource (not the actual authority held by the user). The valid intended access authorities are ALTER, CONTROL, UPDATE, READ, and NONE. The INTENT operand is valid only with the ACCESS event name.
ALLOWED
specifies a list of allowed access authorities to be selected. An allowed access authority is the actual authority held by the user requesting access to a particular resource (not the minimum authority needed by the user to access that resource). The valid, allowed access authorities are ALTER, CONTROL, UPDATE, READ, and NONE. The ALLOWED operand is valid only with either the ACCESS or the ADDVOL event names.
NEWNAME(name-list...)
specifies a list of new, fully qualified resource names to be selected. This operand is valid only with the RENAME event name.
NEWDSQUAL(name-list...)
specifies a list of qualifiers for new dataset or generic names to be selected. Valid qualifiers are any user IDs or group names used as the high-level qualifier of a dataset name or any qualifiers supplied by the ICHRSMFE installation-wide exit routine. This operand is valid only with the RENAME event name.
LEVEL(begin-number:end-number) or LEVEL(number-list)
specifies a range (in ascending order) or a list of resource levels to be selected.

The meaning of the level indicator is set by your installation with the ADDSD, ALTDSD, RDEFINE, and RALTER commands. See z/OS Security Server RACF Command Language Reference for more information about the LEVEL operand.

LIST subcommand

The LIST subcommand formats and prints a listing of each individual RACF SMF record (both PROCESS and STATUS) that passes the selection criteria specified on the SELECT and EVENT subcommands. On the LIST subcommand, you can specify the title, sort sequence, and format control for the listing. The RACF report writer processes only one LIST subcommand at a time; if you enter more than one, the RACF report writer recognizes only the last LIST subcommand that you have entered. (The RACF report writer does all processing after you enter the END command.)

If you want to execute a LIST subcommand more than once to produce your reports, you must run the report writer each time. If you use the same selection criteria for each LIST subcommand you run, use the SAVE operand on RACFRW to specify the work-data set that is to contain the selected, reformatted SMF records. In this way, you can avoid unnecessary processing each time you run the report writer.

The syntax of the LIST subcommand:

{LIST}       [TITLE('q-string')]
{L   }

             [SORT( [DATE] [TIME] [SYSID]      ]
             [      [USER] [GROUP] [EVENT]     ]
             [      [EVQUAL] [TYPE] [NAME]     ]
             [      [CLASS] [TERMINAL] [JOBID] ]
             [      [OWNER] [SECLABEL]         ]
             [      [APPLAUDIT])               ]

             [{ASCEND }]
             [{DESCEND}]

             [NEWPAGE]
TITLE(‘q-string’)
specifies a string of up to 132 characters, enclosed in single quotation marks, to be used as the heading for each page of this particular listing. If you omit this operand but specify a default heading in the TITLE operand of the RACFRW command, the default heading appears on each page of the listing. If you omit both this operand and the RACFRW TITLE operand, no heading at all appears on the listing.
SORT(field-list)
specifies the fields of the input record (a reformatted RACF SMF record) that are to be used for sorting. If you specify the LIST subcommand without specifying the SORT operand, the RACF report writer sorts the records by RCDTYPE, at offset 5(5) in the reformatted SMF record, with STATUS records preceding PROCESS records. If you specify SORT operand values, the records are then further sorted within the STATUS and PROCESS groups by the fields that you specify on the SORT operand.

The sequence in which you specify the SORT operands determines the sequence in which the RACF report writer sorts the records. For example, specifying SORT(OWNER GROUP USER DATE TIME) causes the RACF report writer to sort according to the profile owner first, then the group name, then the user name. If you omit the SORT operand, the order in which the records were written to SMF is not necessarily the order in which the records appear in the output listing, unless you have specified EQUALS in the SORTEQU field of the installation-replaceable module (ICHRSMFI).

The following table describes the operands you can use to select a sort sequence. Even though these operands apply only to process records, specifying them does not affect the order of status records.
OPERAND DESCRIPTION
   
DATE Julian date (YYDDDF) that the job entered the system
TIME Time of day (HHMMSSTH)
SYSID System identifier
USER User (job) names
GROUP Group (step) names
EVENT Security-event codes
EVQUAL Security-event code qualifiers
TYPE Event types: 1 = JOB/LOGON events 2 = SVC events 3 = command events
NAME Names of resources within event types: user ID for JOB/LOGON events RESOURCE NAME for SVC and command events
CLASS Resource class names
TERMINAL Terminal ID
JOBID Job ID from SMF job management record
OWNER Owner of the resource
SECLABEL Security label
APPLAUDIT APPLAUDIT key 8-byte key linking records of APPC/MVS transactions
ASCEND
specifies that the fields identified by the DATE and TIME operands are to be sorted in ascending order. If you omit the DATE and TIME operands, this operand is ignored.

ASCEND is the default value.

DESCEND
specifies that the fields identified by the DATE and TIME operands are to be sorted in descending order. If you omit both the DATE and TIME operands, this operand is ignored.
NEWPAGE
specifies that the listing is to start printing on a new page whenever the value in the major (first) sort field changes. If you omit the SORT operand, this operand is ignored.

SUMMARY subcommand

The SUMMARY subcommand causes the RACF report writer to format and print reports that summarize the information in the RACF SMF records that meet the selection criteria on the SELECT and EVENT subcommands.

Using the SUMMARY subcommand, you can request reports that summarize the following:
  • Group activity
  • User activity
  • Resource activity
  • Security-event activity
  • RACF command activity
  • Owner activity
  • Group activity broken down by resource
  • User activity broken down by resource
  • Resource activity broken down by user
  • Resource activity broken down by group
  • Resource activity broken down by security event
  • Security event activity broken down by resource
  • RACF command activity broken down by user
  • RACF command activity broken down by group
  • RACF command activity broken down by resource
  • Owner activity broken down by resource.

On a SUMMARY subcommand, you can specify only one of the activities mentioned in the preceding list. You can, however, enter as many as 16 different SUMMARY subcommands for each RACFRW command. You can thus request reports of all possible activities in one run of the RACF report writer. (Note that, if you accidentally enter more than one SUMMARY subcommand for the same type of activity, it does not cause an error; the RACF report writer recognizes only the last one.) The order in which you enter the SUMMARY subcommands is the order in which the summary reports are printed.

The syntax of the SUMMARY subcommand:

{SUMMARY}      name1   [BY(name2)]
{SUM    }

               [ {VIOLATIONS} ]
               [ {SUCCESSES } ]
               [ {WARNINGS  } ]

               [NEWPAGE]

               [TITLE('q-string')]
name1
specifies the major field on which information is to be grouped and summarized. The valid values for name1 are: GROUP, USER, RESOURCE, EVENT, COMMAND, and OWNER.
BY(name2)
specifies a minor field within the major field on which information is to be grouped and summarized also. The valid values for name2 are: GROUP, USER, RESOURCE, and EVENT.
Note: Only the following single name and name1 [BY(name2)] combinations are valid:
Name name1 [BY(name2)]
GROUP RESOURCE BY(USER)
USER RESOURCE BY(GROUP)
RESOURCE RESOURCE BY(EVENT)
EVENT EVENT BY(RESOURCE)
COMMAND COMMAND BY(USER)
OWNER COMMAND BY(RESOURCE)
GROUP BY(RESOURCE) COMMAND BY(GROUP)
USER BY(RESOURCE) OWNER BY(RESOURCE)
VIOLATIONS
specifies that only information about access violations is to be included in the summary.
SUCCESSES
specifies that only information about successful access attempts is to be included in the summary. If you omit VIOLATIONS, SUCCESSES, and WARNING, the summary includes information for both access violations and successful access attempts.
WARNINGS
specifies that only accesses that were successful only because WARNING mode was in effect are to be included in the summary. The information appears under the WARNINGS heading.

If you do not specify VIOLATIONS, SUCCESSES, or WARNINGS, the report summarizes all access attempts.

NEWPAGE
specifies that the summary report is to start printing on a new page whenever the value in name1 changes. NEWPAGE is valid only when BY(name2) is specified.
TITLE(‘q-string’)
specifies a string of up to 132 characters, enclosed in single quotation marks, to be used as the heading for each page of this particular summary report. If you omit this operand but specify a default heading in the TITLE operand of the RACFRW command, the default heading appears on each page of the summary report. If you omit both this operand and the RACFRW TITLE operand, no heading at all appears on the summary report.

END subcommand

The END subcommand terminates subcommand mode. All report-generation processing is done after you enter the END subcommand.

The syntax of the END subcommand:

END

Using the RACF report writer

The following detailed descriptions of these tasks include brief examples of the report writer command and subcommands needed for each. (In the examples, lowercase entries can be modified to suit the needs of your installation.) For sample reports, see Sample reports.

Monitoring password violation levels

Monitoring password violation levels enables you to:
  • Determine how effectively new RACF users are coping with the LOGON process
  • Determine if the number of password violations stabilizes over time
  • Determine where (at which terminals) these password violations are occurring.
To obtain a report that describes password violations, you can use the following command and subcommands:
RACFRW GENSUM...
SELECT PROCESS
EVENT LOGON EVQUAL(1)
LIST ...
END

Results—Monitoring password violation levels

These subcommands create a general summary report and a listing of the selected process records. (See Figure 5 and Figure 7 for samples of the general summary report and listings of selected process records.)

The total number of job or logon violations in the general summary report includes all types of violations (invalid password, invalid group, invalid OIDCARD, and invalid terminal). Because the EVENT subcommand causes the RACF report writer to select only those process records that describe an invalid password, you can use the number of process records selected to determine the percentage of password violations. If, for example, the number of process records selected is 13 and the total number of job or logon attempts is 393, you can compute the percentage of password violations by dividing 13 by 393. In this particular example, the value is 3.3%.

The violation percentage is a useful number to record and track over time. As users become more familiar with using their user ID and password, this percentage should tend to stabilize at a relatively low level.

You can look at the terminal name in the listing of process records to determine where persistent violations are originating. The records selected are record types 20, 30, and 80 (process records) with an event code of 1 for job initiation or TSO logon. (See Figure 2 for a list of RACF events and their qualifiers.)

Monitoring access attempts in WARNING mode

Your installation may choose to use warning mode during the initial implementation of RACF. During this period, resource profiles contain a warning indicator (specified when the owner creates or later changes the profile). When the warning indicator is set, RACF allows all requesters to access the resource, and, if the requester would not otherwise be allowed access, RACF sends a message to the requester. Logging occurs at the owner-specified access type and level.

If the owner of a resource has specified in the profile one of the following:
  • AUDIT(FAILURE(READ))
  • AUDIT(ALL(READ)) (or the defaults for these are in effect)
or if you, as auditor, specify one of the following:
  • GLOBALAUDIT (FAILURE(READ))
  • GLOBALAUDIT (ALL(READ))
RACF logs each access to the resource, and you can use the RACF report writer to provide a list of the accesses RACF allowed only because the warning indicator was set.

Using the warning indicator can help your installation to migrate gradually to RACF. Checking the requesters and resources in the report-writer listing can enable you to develop access lists without disrupting authorized work and without the immediate need to write and test a RACF exit routine.

As the auditor, however, you must be aware that if your installation sets the warning indicator in a resource profile any requester can access the resource. You should verify that the profile for a highly classified resource (such as payroll or business-planning data) does not contain the warning indicator.

To obtain a list of the profiles in a particular class that have the warning indicator set, you can issue the RACF SEARCH command with the WARNING operand:
SEARCH  CLASS(class-name)  WARNING
For example, to list the profiles in the TERMINAL class that contain the warning indicator, enter:
SEARCH  CLASS(TERMINAL)  WARNING
To obtain a report of accesses granted only because the warning indicator was set, you can use the following command and subcommands:
RACFRW ...
 SELECT PROCESS WARNINGS
 LIST ...
END

Results—Monitoring access attempts in WARNING mode

These subcommands produce a listing of the selected process records. The records selected are those that contain an event code of 2 for resource access and a qualifier from the following table.
EVENT NUMBER
DESCRIPTION
3
Warning issued because of access.
5
Warning issued because of PROTECTALL.
8
Warning issued because of missing security label from job, user, or profile.
9
Warning issued because of insufficient security label authority.
10
Warning issued because data set is not cataloged.
13
Warning issued because of insufficient CATEGORY/SECLEVEL.

The WARNING indicator is also set in records for the following events: LOGON, RENAME, DEFINE.

Monitoring access violations

When warning mode is in effect, and during normal operation of RACF, it is essential to your job as an auditor that you be able to monitor access violations. RACF detects and logs an access violation when it denies a user access to a resource because that user is not authorized to access the resource. An access violation is, therefore, a symptom that someone either does not understand their role as a RACF user or is trying to bypass RACF protection. You can use a report of access violations to identify such users and to to help your installation identify when it may need to change access lists or universal access codes (UACCs).

You can request the report for data set violations and for violations in any of the classes identified in the class descriptor table.

To obtain an access violation report, you can use the following command and subcommands with the resource classes for which you want information:
RACFRW ...
 LIST ...
  SELECT PROCESS
   EVENT ACCESS EVQUAL(1) CLASS(a valid resource class,...,
         a valid resource class)
   EVENT LOGON  EVQUAL(4)
END

Results—Monitoring access violations

These subcommands create a listing of all process records that meet the criteria set in the EVENT subcommands. The EVENT ACCESS subcommand selects all process records that contain access violations for the specified classes (an event code of 2 and an event qualifier of 1). The EVENT LOGON subcommand expands the scope of the report to include all user attempts to log on from a terminal or console the user is not authorized to use (an event code of 1 and an event qualifier of 4).

Monitoring the use of RACF commands

In any installation, the security administrator is probably the most frequent user of RACF commands. Occasionally, users without any privileged attributes may enter ADDSD, PERMIT, or RDEFINE, or another, similar command against one of their resources; however, some users may try to use the whole range of RACF commands. Unless the user is authorized, RACF does not execute the command. Each unauthorized attempt to use a RACF command, however, represents a potential security violation, an event that you should know about. You monitor the use of commands with the command-summary report.

To obtain a command-summary report, you can use the following command and subcommand:
RACFRW ...
 SUMMARY COMMAND BY (USER)
END

A sample command-by-user summary report appears in Figure 20.

If you detect certain users making persistent, unauthorized use of RACF commands, you can extract the details of the commands used and the resources involved. To obtain details of any command violations logged for specific users, use the following command and subcommands:
RACFRW ...
SELECT VIOLATIONS USER(userid(s) ...)
LIST ...
END

Where userid(s) is the ID of the user making unauthorized use of RACF commands. Note that RACF does not automatically log the events that these reports describe. To obtain meaningful data, you must direct RACF to log the activities of specific users or command violations or both. The reports are useful only after RACF has logged the events for the time interval that is meaningful to you. See Monitoring specific users, Monitoring SPECIAL users, and Monitoring OPERATIONS users for related information.

Monitoring specific users

If you have directed RACF, either through the UAUDIT operand on the ALTUSER command or the corresponding ISPF panel, to log the RACF-related activities of one or more specific users, you can use the report writer to obtain a listing of the activities of these users.

To obtain a listing of all records RACF has logged because you requested auditing of one or more specific users, you can use the following command and subcommands:
RACFRW ...
  SELECT PROCESS REASON(USER) ...
  LIST ...
END

Monitoring SPECIAL users

If you have directed RACF, either through the SAUDIT operand on the SETROPTS command or the corresponding ISPF panel, to log the RACF-related activities of SPECIAL or group-SPECIAL users, you can use the report writer to obtain a listing of the activities of these users.

To obtain a listing of all records RACF has logged because you requested auditing of SPECIAL or group-SPECIAL users or because the command required the SPECIAL or group-SPECIAL attribute and the user had it, you can use the following command and subcommands:
RACFRW ...
   SELECT PROCESS AUTHORITY(SPECIAL)
  LIST ...
END

Monitoring OPERATIONS users

The OPERATIONS and group-OPERATIONS attributes are very powerful. OPERATIONS allows a user access to almost all resources. Group-OPERATIONS allows a user access to almost all resources within the scope of the group and its subgroups. (The only resources not accessible to the OPERATIONS or group-OPERATIONS user are those that have been explicitly barred by placing the OPERATIONS user in the access list of a resource with an access level of NONE at either the user ID level or the group level.) Therefore, you should carefully monitor the activities of these users to ensure that all accesses to installation resources are for valid reasons.

To obtain a report of the activities of OPERATIONS and group-OPERATIONS users, you can use the following command and subcommand:
RACFRW ...
  LIST ...
   SELECT PROCESS AUTHORITY(OPERATIONS)
END
Note: RACF logs the activities of users with the OPERATIONS and group-OPERATIONS attributes if the following are true:
  • The SETROPTS OPERAUDIT is in effect.
  • The access to the resource was successful because the user had the OPERATIONS or group-OPERATIONS attribute.

Monitoring failed accesses to resources protected by a security level

If you have directed RACF, through the SECLEVELAUDIT operand on the SETROPTS command or on the corresponding ISPF panel, to log accesses to resources that are protected by a security level, you can use the report writer to obtain a listing of any access attempts that have failed because the user did not have the sufficient security classification to access the resource.

When security-level auditing is in effect, RACF logs all attempts to access any resource protected by a given security level (such as confidential) or higher. Therefore, you can create a report to list access violations to those protected resources and determine which users are attempting to access sensitive information at your installation.

To obtain a report of unauthorized access attempts to resources with a security-level classification, you can use the following command and subcommands:
RACFRW
   SELECT PROCESS REASON(SECAUDIT)
    EVENT ACCESS EVQUAL(6) CLASS(a valid resource class,. . .,
         a valid resource class)
 LIST
END

Results—Monitoring failed accesses to resources protected by a security level

These subcommands create a listing of all process records that have been logged because security-level auditing was in effect (REASON(SECAUDIT)) and meet the criteria set in the EVENT ACCESS subcommand (event code 2). The EVENT subcommand selects all failed attempts (event qualifier 6) to access any resource within the resource class that has a security level equal to or higher than the level specified on the SECLEVELAUDIT operand of the SETROPTS command or on the corresponding ISPF panel.

Monitoring accesses to resources protected by a security label

If you have directed RACF, through the SECLABELAUDIT operand on the SETROPTS command or on the corresponding ISPF panel, to log accesses to resources that are protected by a security label according to the audit options in the SECLABEL profile, you can use the report writer to obtain a listing of all attempts to access the resource.

When the SECLABELAUDIT option is in effect, RACF logs accesses to resources by SECLABEL. Therefore, you can create a report to list attempts to access those protected resources and determine which users are attempting to access sensitive information at your installation.

To obtain a report of attempts to access resources with a security label, you can use the following command and subcommands:
RACFRW
   SELECT PROCESS REASON(SECLABELAUDIT)
    EVENT ACCESS
 LIST
END

Results—Monitoring accesses to resources protected by a security label

These subcommands create a listing of all process records that have been logged because the security-label auditing option was in effect (REASON(SECLABELAUDIT)) and meet the criteria set in the EVENT subcommand ACCESS (event code 2).

RACF report writer examples

This section gives some examples of how to use the RACF report writer command and subcommands to produce various reports.

The first five examples show how to obtain single reports; however, to create all the reports that you require at your installation, you may need to execute the RACF report writer more than once.

An execution of the RACF report writer consists of the RACFRW command, report definition subcommands, and the END subcommand. Example 5 shows how the report writer executed a series of subcommands to produce multiple reports that you did not intend to produce; example 6 shows how you can correct the subcommands to produce the number of reports you want.

Example 1—Obtaining a report for all RACF SMF records

To obtain a report of all RACF SMF records, listed in the order read from the input file, and a general summary report, showing overall RACF-related system activity, enter:
  • RACFRW TITLE('BIG LISTING') GENSUM
  • LIST
  • END

Example 2—Obtaining a report for all MVS jobs run by users not defined to RACF

To obtain a report of all batch jobs that are not associated with RACF or a RACF-defined user, or all jobs run by TSO users, or started tasks not defined to RACF, enter:
  • RACFRW
  • SELECT NOUSER PROCESS
  • LIST TITLE('JOB LIST REPORT') SORT(USER) NEWPAGE
In the example, RACF selects only those process records that meet the criteria and sorts by job name.
To obtain a summary of these jobs, enter:
  • SUMMARY RESOURCE TITLE('JOB SUMMARY REPORT')
  • END

Example 3—Obtaining a report for data set violations

To obtain a report of all violations against data sets owned by USERA (USERA is the high-level qualifier of the data-set name) in January 1989, sorted in date and time sequence, enter:
  • RACFRW TITLE('USERA DATASETS LIST REPORT')
  • SELECT VIOLATIONS DATE(89001:89031)
  • EVENT ALLSVC CLASS(DATASET) DSQUAL(USERA)
  • EVENT ALLCOMMAND CLASS(DATASET) DSQUAL(USERA)
  • LIST SORT(DATE TIME)
To obtain a summary of this activity, enter:
  • SUMMARY RESOURCE BY(USER) TITLE('USERA DATA SETS SUMMARY REPORT')

Example 4—Obtaining a report for data set activity by job, system, and user

To obtain a report on data set activity by (a) jobs A and B on system 308A and (b) users C and D on system 308B, enter:
  • RACFRW
  • SELECT JOB(A B) NOUSER SYSID(308A)
  • EVENT ALLSVC CLASS(DATASET)
  • EVENT ALLCOMMAND CLASS(DATASET)
  • SELECT USER(C D) NOJOB SYSID(308B)
  • EVENT ALLSVC CLASS(DATASET)
  • EVENT ALLCOMMAND CLASS(DATASET)
  • LIST TITLE('SELECTED DATA SET ACTIVITY REPORT') SORT(SYSID)
  • END

Example 5—Obtaining multiple reports the wrong way

Situation

Assume you need to produce the following separate reports:
  • A detailed listing of all access violations, sorted by user
  • A resource-by-user summary report, with totals for access violations only
  • A listing of all successful accesses, sorted by date and time
  • A resource-by-user summary report, with totals for successful accesses only.
You must produce these four separate reports because each report is to be distributed to four different people, each of whom is entitled to see only the information on one report.
Assume that you enter:
(1)
RACFRW
(2)
SELECT VIOLATIONS
(3)
LIST TITLE('ACCESS VIOLATIONS LIST REPORT') SORT(USER)
(4)
SUMMARY RESOURCE BY(USER) TITLE ('ACCESS VIOLATIONS SUMMARY REPORT')
(5)
SELECT SUCCESSES
(6)
LIST TITLE('ACCESS SUCCESS LIST REPORT') SORT(DATE TIME)
(7)
SUMMARY RESOURCE BY(USER) TITLE('ACCESS SUCCESS SUMMARY REPORT')
(8)
END

Results—Obtaining multiple reports the wrong way

Instead of receiving the four requested reports, you receive two reports:
  • A list report of all violations and successes, sorted by date and time
  • A summary report of resources-by-user, with both violations and successful accesses.

How RACF executed

Here is what happened:
  • RACF record selection

    You intended to first select, list, and summarize only violations from the SMF input file (statements 2, 3, and 4). Second, you wanted to select, list, and summarize only successful accesses (statements 5, 6, and 7), and finally, you wanted to produce two summary reports, one for access violations and one for access successes (statements 4 and 7).

    However, the RACF report writer does not execute in that sequence. RACF first selects records based on all the SELECT and EVENT subcommands entered between the RACFRW command and the END subcommand. Only after this selection process is complete are any of the requested reports produced. In this example, the RACF report writer checked each record from the input file to see whether it was either an access violation (statement 2) or a successful access (statement 5). Because all of the SMF records met at least one of these conditions, the RACF report writer selected all of the records for further processing.

  • RACF LIST function

    The RACF report writer next produced a single list report (statement 6). RACF ignored the first LIST subcommand (statement 3) because only one LIST subcommand, the last one entered (statement 6), is valid for each execution of the RACF report writer. The report that was produced listed by date and time all the records selected (both access violations and successful accesses) as specified in statement 6.

  • RACF SUMMARY report

    Next, the RACF report writer produced a single summary report (statement 7). Because the SUMMARY subcommand in statement 4 is the same as that in statement 7, RACF ignored the first SUMMARY subcommand and produced one summary report. If you enter identical SUMMARY subcommands between RACFRW and END, RACF only uses the last subcommand and produces one summary report.

    Thus, the single summary report for this example produced totals for all the records selected (both access violations and successful accesses).

Example 6—Obtaining multiple reports the correct way

To produce the four listings that you intended, enter two separate RACFRW commands:
(1)
RACFRW
SELECT VIOLATIONS
LIST TITLE('ACCESS VIOLATIONS LIST REPORT') SORT(USER)
SUMMARY RESOURCE BY(USER) TITLE ('ACCESS VIOLATIONS SUMMARY REPORT')
END
(2)
RACFRW
SELECT SUCCESSES
LIST TITLE('ACCESS SUCCESS LIST REPORT') SORT(DATE TIME)
SUMMARY RESOURCE BY(USER) TITLE ('ACCESS SUCCESS SUMMARY REPORT')
END
Note: RACF interprets each RACFRW command separately and produces the four reports. To ensure you get the reports you want:
  1. If you want to store the results in a GDG data set, use DISP=MOD on your JCL to prevent the results of the second RACFRW operation from writing over the results of the first.
  2. After the first SELECT/LIST/SUMMARY subcommands (for RACFRW in statement 1), be sure to enter END.
  3. Run the RACFRW command again (statement 2) for the second SELECT/LIST/SUMMARY subcommands and enter END.