How the RACF report writer operates

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.

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

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.

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.

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:

Planning considerations

The RACF report writer and the SMF input data set

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.

/*****************************************************************
/*****************************************************************
/*                                                               *
/*              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

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.

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

Useful hints

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:

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}]

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.

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.

RACFRW
SELECT VIOLATIONS
EVENT LOGON
SELECT SUCCESSES
EVENT SETROPTS
LIST
END

RACFRW
SELECT VIOLATIONS
SELECT SUCCESSES
EVENT LOGON
EVENT SETROPTS
LIST
END

RACFRW
LIST
END

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.

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

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.

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

RACFRW GENSUM...
SELECT PROCESS
EVENT LOGON EVQUAL(1)
LIST ...
END

Results

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.

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.

SEARCH  CLASS(class-name)  WARNING

SEARCH  CLASS(TERMINAL)  WARNING

RACFRW ...
 SELECT PROCESS WARNINGS
 LIST ...
END

Results

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.

RACFRW ...
 LIST ...
  SELECT PROCESS
   EVENT ACCESS EVQUAL(1) CLASS(a valid resource class,...,
         a valid resource class)
   EVENT LOGON  EVQUAL(4)
END

Results

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.

RACFRW ...
 SUMMARY COMMAND BY (USER)
END

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

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.

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.

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.

RACFRW ...
  LIST ...
   SELECT PROCESS AUTHORITY(OPERATIONS)
END

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.

RACFRW
   SELECT PROCESS REASON(SECAUDIT)
    EVENT ACCESS EVQUAL(6) CLASS(a valid resource class,. . .,
         a valid resource class)
 LIST
END

Result

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.

RACFRW
   SELECT PROCESS REASON(SECLABELAUDIT)
    EVENT ACCESS
 LIST
END

Result

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

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

Example 3—Obtaining a report for data set violations

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

Example 5—Obtaining multiple reports the wrong way

Situation

Result

How RACF executed

Example 6—Obtaining multiple reports the right way