ACFRULCU - Rule Cleanup Utility

Use the Rule Cleanup Utility (ACFRULCU) to identify rule lines that are no longer needed.
acf2src
The Rule Cleanup Utility (ACFRULCU) identifies rule lines that are no longer needed. The lines can be from logonids or roles that no longer exist or UIDs that are no longer valid. You can also specify specific UIDs, logonids, or roles to remove from the targeted rules. You can use the utility for access rules, resource rules, and DB2 rules. The utility can be run against the active databases or alternate databases.
You can specify parameters that define the type and location of the rules against which the utility runs. If no parameters are supplied, the utility runs against access rules in the active CA ACF2 databases and removes only rule lines where the UID string in the rule line no longer exists.
ACFRULCU generates ACFNRULE statements to an output file with the recommended rule changes. You must process the statements in a subsequent step (in a batch or TSO environment) to perform the actual rule updates. The utility, by itself, does not delete or modify any rules.
The first time that you run this utility, use the UIDNXIST parameter. The UIDNXIST parameter specifies all rule lines that have a UID value that no longer matches values for any logonid. This setup is useful if the LID is part of the UID string. The output from the utility is all rule lines that are specifically for logonids that no longer exist. If you are using roles, the ROLNXIST parameter detects any rule line in a $ROLESET rule set that specifies a non-existent user value. You can use ROLNXIST with ROLESYS to identify rule lines that contain a value for a non-existent role value.
Clean Up Rules Manually
You can run the ACFRULCU utility using ISPF panels to manually set up your rule cleanup preferences.
Follow these steps:
  1. Select the Rules option on the Primary Option Menu.
  2. Select the Rule Cleanup Utility option on the Rules Processor Menu.
  3. Complete the Rule Cleanup panel as follows:
    1. Choose the type of rules to clean up:
      ACCESS
      Displays the Access Rule Cleanup panel, where you specify the access rule keys to clean up.
      RESOURCE
      Displays the Resource Rule Cleanup panel, where you specify the resource rule keys to clean up.
      CA ACF2 for DB2
      Displays the CA ACF2 for DB2 Rule Cleanup panel, where you specify the DB2 resource rule keys to clean up.
    2. Select the options for the utility:
      Perform actual cleanup?
      Specifies whether to perform cleanup (Y) or produce only a report containing statements (N). If you select N, you can save the report, review its content, and execute at your convenience.
      Include all KEYS in the cleanup?
      Specifies whether to include all keys. If you choose N, you can build a list.
      Run against current ACTIVE databases?
      Specifies whether to run the utility against the active databases (Y) or against alternate databases (N). Choosing N prompts you to specify the databases to use.
      List rules after ACFNRULE is performed?
      Specifies whether to list rules after ACFNRULE performs cleanup.
      Clean up UIDs from the rule lines?
      Specifies whether to remove UIDs from the rule lines (Y) or remove user-related or role-related lines from rules (N). Each choice displays a panel on which you can provide specific information.
    3. Specify JOB statement information for the job being generated.
      Press Enter.
      Another rule cleanup panel appears, requesting SYSOUT information.
    4. Specify the name of the SYSOUT data set created by the utility to store generated command statements for performing the cleanup. Data set requirements are as follows: DSORG=PS, RECFM=FB, LRECL=80.
    When you have completed all panels as needed, the product produces JCL that you can submit to perform the cleanup.
  4. Press the END key, then enter Y on the confirmation panel to submit the job.
    The product executes the job as follows:
    • If you elected to perform cleanup, the job executes the utility and executes the utility commands to conduct cleanup.
    • If you elected to create only a report, the job produces the report containing ACFNRULE statements and sends the statements to an output file with the recommended rule changes. You can save the report, review its content, and execute at your convenience.
Clean Up Rules by Submitting a Batch Job
You can enter ACFRULCU parameters on the command line in the TSO environment and from the JCL PARM field in batch.
Use JCL that is similar to the following JCL.
The value that you specify for REGION depends on the number of UIDs defined in the logonid database. With 1024 UIDs defined, 128K is sufficient to run. For each additional 1024 UIDs, add 30K to the region size. The storage for handling UIDs in the utility gets allocated above the 16M line if possible.
//ACFRULCU JOB 1,'RULE CLEANUP' //CLEANUP EXEC PGM=ACFRULCU, REGION=???? //LOGONIDS DD DSN=ACF2.ALTLID,DISP=SHR //RULES DD DSN=ACF2.ATLRULES,DISP=SHR //INFOSTG DD DSN=ACF2.ALTINFO,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSOUT DD DSN=ACFRULCU.ACFNRULE.STMTS,DISP=OLD //SYSIN DD * NOACF2 CLASS(R) TYP(CKC) MKEY(C***) EXCLKEY(CSSF) MUID(***XYZ) /*
File specifications are as follows:
  • SYSPRINT
    Specifies a file for all error messages. This ddname must be specified and is opened whenever error conditions exist. If ACFNRULE is run as a TSO command, messages are displayed on the terminal. Data set requirements are as follows: DSORG=PS, RECFM=VBA, LRECL=137.
  • SYSOUT
    Specifies a data set that stores the ACFNRULE command statements that are generated by ACFRULCU. Data set requirements are as follows: DSORG=PS, RECFM=FB, LRECL=80. We recommend BLKSIZE=3120.
  • SYSIN
    Specifies the data set where all ACFRULCU parameter statements are supplied. A SYSIN ddname statement is required. Data set requirements are as follows:
    DSORG=PS, RECFM=FB. Also, SYSIN must be inline or from an LRECL=80 fixed block data set.
  • LOGONIDS
    Specifies the data set name that contains the logonid records on the alternate database that the utility should use in its processing. This parameter should be used only if you specify the NOACF2 parameter.
  • RULES
    Specifies the data set name that contains the rule records on the alternate database that the utility should use in its processing. This should only be used if you specify the NOACF2 parameter.
  • INFOSTG
    Specifies the data set name that contains the infostorage records on the alternate database that the utility should use in its processing. Use only if you specify the NOACF2 parameter.
    The following parameter identifies the databases to use:
  • [ACF2|NOACF2]
    Identifies databases that the rule cleanup utility uses.
    • ACF2
      Uses the active databases.
    • NOACF2
      Uses alternate databases that are referenced by the LOGONIDS, RULES, and INFOSTG input files.
      If you execute the ACFNRULE statements generated by the rule cleanup utility, the active database files on the system are updated, regardless of which files are used as input. ACFNRULE always updates the active databases.
The following parameters specify the type of rules to process:
  • [SYSID(
    name
    )]
    Specifies a SYSID to use when processing resource rules that are not CLASS(R). For example, in DB2, the SYSID is the DB2 subsystem ID. This field is maskable with asterisks (*) only. A dash is not an acceptable masking character for SYSID and is treated as a literal character. If this parameter is omitted, all rules are processed for specified CLASS and TYPE.
  • [DSET]
    Specifies that the access rules should be processed. If you specify DSET, you cannot specify TYPE or CLASS. If no CLASS is specified, DSET is the default.
  • [CLASS(
    code
    )]
    Identifies the class of infostorage rules to be processed. For example, specifying CLASS(D), the utility processes DB2 rules. Specifying CLASS(R), the utility processes resource rules.
  • [TYPE(
    type1
    [,[
    type2
    ],[
    type3
    ],…,[
    typen
    ]] ))]
    Specifies the types of infostorage rules to be processed. Types are represented by character codes, one to three characters in length. If you specify TYPE, you must also specify CLASS. For example, TYPE(CKC) with CLASS(R) indicates that the utility should process resident CICS resource rules. TYPE(C**,ABC) with CLASS(R) indicates that the utility should process all TYPE values that conform to the C** mask and values that have a TYPE value of ABC. This field is maskable with asterisks (*) only. A dash is not an acceptable masking character for type and is treated as a literal character. If CLASS is specified, but no TYPE is indicated, the utility processes all types of that class.
    Limit
    : Ten TYPE values
  • [EXCLTYPE(
    type1
    [,[
    type2
    ],
    type3
    ],…,[
    typen
    ]] )]
    Specifies the types of infostorage rules to be excluded from processing. Types are represented by character codes, one to three characters in length. If you specify EXCLTYPE, you must also specify CLASS. For example, EXCLTYPE(CKC) with CLASS(R) indicates that the utility should not process resident CICS resource rules. TYPE(C**,ABC) with CLASS(R) indicates that the utility should not process any TYPE values that conform to the C** mask and should exclude resource rules that have a TYPE value of ABC. This field is maskable with asterisks (*) only. A dash is not an acceptable masking character for type and is treated as a literal character. If a TYPE is specified, but no EXCLTYPE is indicated, the utility processes all types of that class.
    Limit
    : Ten EXCLTYPE values
The following parameters identify the rule sets to process. The parameters define the key values for the rule sets that the utility runs against. You can specify any or all of the parameters. If none of the key value parameters are specified, the default is all key values.
  • [KEY(
    name1,name2,…,namen
    )]
    Specifies a list of 1- to 40-character $KEY values identifying the rule sets to be processed for the UIDs, LIDs, or roles. The field is not maskable.
  • [MKEY(
    name1,name2,…,namen
    )]
    Specifies a list of 1- to 40-character $KEY masked values identifying the rule sets that are to be processed for the UIDs, LIDs, or roles. MKEY can be specified with KEY, but the parameters are processed separately.
  • [EXCLKEY(
    name1,name2,…,namen
    )]
    Specifies a list of 1- to 40-character $KEY values identifying the rule sets to exclude from processing for the UIDs, LIDs or roles. This field cannot be masked. Use this parameter to exclude records from the records that were already chosen by the KEY or MKEY parameters.
  • [MEXCLKEY(
    name
    )]
    Specifies a list of 1- to 40-character $KEY masked values identifying the rule sets to exclude from processing for the UIDs, LIDs, or roles. Use this parameter to exclude records from the records that were already chosen by the KEY or MKEY parameters.
The following parameters identify the UIDs and logonids to process:
  • [LID(lid1,lid2,...,lidn)]
    Specifies a list of one- to eight-character logonids to remove from any rule set in which they are referenced. This parameter should only be used if the LID is part of the UID string.
    LID values should
    not
    begin with a space. If a space is added to the beginning of a LID value, the value will not be processed and the next value is evaluated. If using multiple lines to specify LID values, add a comma to the end of each line to continue to the next value. This includes the beginning of the LID parameter.
    LID(, LID1, LID2, ..., LIDN)
  • [UID(string1,string2,…,stringn)]
    Specifies a list of 1- to 24-character UID string values to remove from the targeted rule sets. Masking is not permitted. If UID(X****JOE) is specified, it matches a UID field of a rule line that has X****JOE only and would not match *****JOE. To do this type of matching, you must use MUID.
    You can clean up UID-based rules or role-based rules, but you cannot specify both on a single run of the utility.
  • [UIDNXIST]
    Specifies to remove all rule lines from the targeted rule sets that do not have a UID that directly identifies an existing logonid record.
    Use this keyword only if the logonid is part of the UID.
    Specify the keyword the first time that you use the utility to strip dead rules from the database, then use they keyword periodically to keep the databases lean. If you do not specify LID, UID, or MUID, this keyword is the default.
    If you are using distributed database (DDB), use caution in determining which ACFNRULE statements you execute. ACFNRULE command lines could be generated to remove UIDs that are still valid on another system.
  • [MUID(
    string1,string2,…,stringn
    )]
    Specifies a list of 1- to 24-character UID masks for which rule lines should be removed from the targeted rule sets. Standard masking conventions apply. For example, specifying MUID(ABC**DEF) for a rule that contains UID(AB*D*DEF) would not result in that rule line being deleted; however, MUID(AB***DEF) or MUID(AB-) would delete that rule line.
  • [EXCLUID(
    string1,string2,…,stringn
    )]
    Specifies a list of 1- to 24-character UID strings for which rule lines should not be removed from the targeted rule sets. This parameter specification overrides the values that are defined in UID, MUID, and UIDNXIST. Asterisks are treated as characters in this keyword. For example, EXCLUID(X**X) excludes only the UIDs that were specified as UID(X**X) in a rule line; it would not exclude UID(XXXX). To exclude UID(XXXX), you must use MEXCLUID(X**X). Use this parameter to exclude records from the records that were already chosen by the UID or MUID parameter.
  • [MEXCLUID(
    string1,string2,…,stringn
    )]
    Specifies a list of 1- to 24-character masked UID strings for which rule lines should not be removed from the targeted rule sets. This parameter specification overrides the values that are defined in UID, MUID, and UIDNXIST.
The following parameters identify the users and roles to process:
  • [USER(
    lid1,lid2,...,lidn
    )]
    Specifies a list of one- to eight-character logonids to remove from any rule set in which they are referenced.
  • [ROLE(
    role1,role2,...,rolen
    )]
    Specifies a list of one- to eight-character role values to remove from any rule set in which they are referenced.
  • [USRNXIST]
    Specifies to remove all rule lines from the targeted rule sets that have a USER value that no longer exists.
    If you are using DDB, use caution in determining which ACFNRULE statements you execute. ACFNRULE command lines could be generated to remove USERs that are still valid on another system.
  • [ROLNXIST]
    Specifies to remove all rule lines from the targeted rule sets that have a ROLE value that no longer exists. X(ROL) records can be identified by a SYSID. When using ROLNXIST against the active databases, the role records are identified by the current SYSID. When using ROLNXIST against alternate databases, you must also specify ROLESYS to identify the SYSID of the X(ROL) records.
  • [ROLESYS(
    sysid
    )]
    Specifies a one- to eight-character SYSID value that identifies the correct X(ROL) records being used on the system. Required when you are processing rules in the alternate databases and have ROLNXIST specified.
    Specifying the incorrect SYSID might remove the wrong rule lines.
Sample Job for Executing (ACFRULCU)
The following sample shows JCL created in a data set and submitted as a job to execute the CA ACF2 Rule Cleanup Utility to clean up data set access rules and resource rules.
//ACFRULCU JOB 1,'RULE CLEANUP' //* //* THIS STEP EXECUTES THE ACFRULCU RULE CLEANUP UTILITY //* TO CREATE STATEMENTS FOR DATA SET ACCESS RULE CLEANUP. //* //ACFRULCU EXEC PGM=ACFRULCU,REGION=256K //LOGONIDS DD DISP=SHR,ACF2.ALTLIDS //RULES DD DISP=SHR,ACF2.ALTRULES //SYSPRINT DD SYSOUT=* //SYSOUT DD DISP=OLD,ACFRULCU.DSN.ACFNRULE //SYSIN DD * UIDNXIST MKEY(-) DSET NOACF2 LIST /* //* Review the statements. BATCH TSO needs to be executed with the statements to do the actual removal. //DELETE EXEC PGM=IKJEFT01 //SYSTSPRT DD SYSOUT=* //SYSTSIN DD DISP=SHR,DSN=ACFRULCU.DSN.ACFNRULE //* THIS STEP EXECUTES THE ACFRULCU RULE CLEANUP UTILITY //* TO CREATE STATEMENT FOR RESOURCE RULE CLEANUP. //* //ACFRULCU EXEC PGM=ACFRULCU,REGION=256K //LOGONIDS DD DISP=SHR,ACF2.ALTLIDS //INFOSTG DD DISP=SHR,ACF2.ALTINFO //SYSPRINT DD SYSOUT=* //SYSOUT DD DISP=OLD,ACFRULCU.RSRC.ACFNRULE //SYSIN * CLASS(R) TYPE(CKC) UIDNXIST MKEY(-) NOACF2 LIST Review the statements. BATCH TSO needs to be executed with the statements to do the actual removal. //DELETE EXEC PGM=IKJEFT01 //SYSTSPRT DD SYSOUT=* //SYSTSIN DD DISP=SHR,DSN=ACFRULCU.DSN.ACFNRULE
Reporting on ACFRULCU
Reporting on what the utility generated is best accomplished by running CA Earl reports against the output file. For example, you could create a CA Earl report to show the rule lines within designated $KEYs that are targeted for deletion for the specified UIDs. The report would look like this:
UID(ABC**DEF) $KEY(SYS1) PARMLIB UID(ABC**DEF) READ(A) EXEC(A) PROCLIB UID(ABC**DEF) READ(A) EXEC(A) $KEY(SYS2) PARMLIB UID(ABC**DEF) READ(A) EXEC(A) PROCLIB UID(ABC**DEF) READ(A) EXEC(A) $KEY(PAYROLL) PAYRATES UID(ABC**DEF) READ(A) EXEC(A) PRIVATE UID(ABC**DEF) READ(A) EXEC(A) UID(A**BCDEF) $KEY(SYS1) PARMLIB UID(A**BCDEF) READ(A) EXEC(A) PROCLIB UID(A**BCDEF) READ(A) EXEC(A) $KEY(CARMA04) JCLLIB UID(A**BCDEF) READ(A) EXEC(A) WORK.ADM UID(A**BCDEF) READ(A) EXEC(A)
The ACFNRULE statements that are generated contain multiple DELETE statements for each key instead of generating one ACFNRULE statement for each delete. An example of these statements looks like this:
ACFNRULE KEY(SYS1) - DELETE(PARMLIB UID(ABC**DEF) READ(A) EXEC(A)) - DELETE(PROCLIB UID(A**BCDEF) READ(A) EXEC(A)) - LIST
This example decreases the number of ACFNRULE statements generated. By only having to decompile each ruleset once within ACFNRULE and, therefore, only getting one relist of each ruleset updated, provides for a faster database update.