Setup of zSecure Admin Command Logger

zSecure Admin provides an option to log all RACF® commands that are issued through the zSecure interface in a central repository. This section provides an overview of the functions and describes the required installation and activation steps.

About this task

The command log records are kept in a z/OS® log stream. Using zSecure functions, it is possible to select and report about the recorded RACF commands. The z/OS log stream must be defined in the LOGR policy data set. The actual recording of the commands in the log stream is done through a started task (CKXLOG) that runs on each system (LPAR) where RACF commands are run. The record of the command can be annotated with a ticket identification and a ticket description. The zSecure Admin ISPF interface and zSecure Command Verifier send the commands to the zSecure Admin Command Logger.

When zSecure Admin is installed and it is verified that it is working properly, the following steps are required for the setup of the zSecure Admin Command Logger function:
  • Step 1: Define a log stream (or log stream model) for use by the Command Logger
  • Step 2: Update C2R$PARM to specify a value for CKXCUST.
  • Step 3: Update the CKXCUST member CKXPARM for installation parameters.
  • Step 4: Define the STC user ID and STARTED profile for the CKXLOG started task.
  • Step 5: Copy the STC procedure to your STC proclib.
  • Step 6: Authorize the STC user ID to allocate and write the log stream.
  • Step 7: Start the CKXLOG started task.
  • Step 8: Define the Command Log policies for components and users.
  • Step 9: Configure the zSecure Admin ISPF user interface for command logging.
  • Step 10: Configure zSecure Command Verifier to ensure logging of commands that are issued in a batch job or from outside the zSecure Admin ISPF interface.
  • Step 11: Optionally, enable calling CKXLOGID from APF environment.
In the above steps, you define new profiles to activate and control various parts of the zSecure Admin Command Logger. The following picture shows a global overview of the flow of a log record, indicating where these different profiles are used:
Figure 1. Global overview of the flow of a log record
Indicates where the different profiles are used
The CKXLOG started task uses resources that start with CKX, as shown in the rectangular box. Access to these resources is used to determine if a log record is written to the logstream or not. Step 8 describes these resources.
The first administrator uses the zSecure Admin ISPF interface to enter changes. The ISPF interface uses the CKR.CKXLOG.** profile and resources that start with CKR as shown in the associated rectangular box. The presence and access of these profiles and resources determine if the zSecure Admin ISPF interface passes command records to the CKXLOG started task. Step 9 describes these resources.
The second administrator enters a command directly without using the zSecure Admin ISPF interface. These commands might be intercepted by zSecure Command Verifier. In that case, logging is controlled through resources that start with C4R, of which a sample is shown in the associated rectangular box. Step 10 describes these resources.

Note that commands that are executed through the zSecure Admin ISPF interace might also pass through zSecure Command Verifier, and might thus be passed to the CKXLOG started task twice: once by zSecure Admin, and once by zSecure Command Verifier. It is the CKXLOG started task that determines whether or not the passed CKXLOG records are actually recorded in the CKXLOG log stream.

Depending on your environment, you might need profiles for one or more of these types of resources, using generic profiles where possible.

Procedure

  1. Define a log stream (or log stream model) for use by the Command Logger.
    The zSecure Admin Command Logger writes the command records to a system-defined log stream. The CKXPARM member defines the name of the log stream. Before a log stream can be used, it must be defined in the system LOGR policy data set using the IXCMIAPU utility. The zSecure Command Logger supports two methods for defining the log stream:
    • The log stream is defined by the systems programmer using the exact name that is specified in CKXPARM.
    • The CKXLOG program itself defines the log stream, based on a predefined log stream model.
    The second method is preferred. The log stream must be defined once and can then be used on all systems that share that LOGR policy data set. The CKXLOG started task tries to open the log stream as it is defined in the CKXPARM. If the log stream does not exist, CKXLOG defines the log stream using the specified (or default) log stream model.

    The log stream can be defined as a DASDONLY log stream; the log stream is dedicated to a single system. It is recommended to use &SYSNAME as its first qualifier. The log stream name is specified in the CKXPARM that you create or update in step 3. Member CKXZLGST in SCKRSAMP is provided as an example for defining a DASDONLY model log stream.

    It is also possible to define a COUPLING FACILITY log stream; the log stream is shared between multiple systems. Member CKXZLGCF in SCKRSAMP is provided as an example for defining a shared model log stream.

    When defining the log stream model, you must consider the retention period and the size of the stream. These are largely dependent on your installation policy and the number of commands issued.

  2. Update C2R$PARM to specify the value for CKXCUST.
    The CKXLOG procedure refers to include member C2R$PARM. C2R$PARM is a sample member that contains JCL SET statements and it is usually referred to as the zSecure configuration. In the zSecure configuration file, the variable CKXCUST is used to name the configuration file for the CKXLOG procedure
    // SET CKXCUST='your.prefix.CKRPARM'

    You normally substitute your.prefix.CKRPARM with the installation CKRPARM data set, but you can specify any partitioned data set with record format FB, and a logical line length of 80. Position 73 to 80 in the records are ignored. This data set must contain the member indicated by the XPARM parameter in the JCL procedure.

  3. Update the CKXCUST member CKXPARM for installation parameters.
    The CKXPARM member in the CKXCUST data set can be used to override the default values for certain parameters. The parameters are set using the SETUP statement. The following SETUP statements are supported:
    SETUP LSNAME(log-stream-name)
    The log-stream-name specifies the name of the log stream that the CKXLOG started task is to use. The qualifier CKXLOG is used to identify the log stream as related to the Command Logger application. It is suggested that the first qualifier indicates the system or sysplex. The log-stream-name can contain system symbols, like &SYSNAME or &SYSPLEX. The default value is &SYSPLEX..CKXLOG
    SETUP LSMODEL(model-log-stream-name)
    The model-log-stream-name specifies the name of the model that the CKXLOG started task is to use if the log stream that the LSNAME specifies does not exist. The qualifier CKXLOG is used to identify the model log stream as related to the Command Logger application. The suggested value for the first qualifier is MODEL. The log-stream-name can contain system symbols, like &SYSNAME or &SYSPLEX. The default value is MODEL.CKXLOG.
    SETUP TICKETEXPIRE(unused-time)
    The CKXLOGID command can be used to set a ticket ID and description. The CKXLOGID command can also be used to clear such a setting. If a ticket ID has not been referenced, it can be automatically removed to free up associated resources. The unused-time specifies the period (HHMM) after which an unreferenced ticket ID is removed from the CKXLOG started task. The default value is 0100 (1 hour).
    Update the CKXPARM member to specify values that are appropriate for your environment.
  4. Define the STC user ID and STARTED profile for the CKXLOG started task.
    If you want to use a dedicated user ID for the CKXLOG started task, you must define the user ID. The user ID and group ID can be assigned to the started task through the STDATA segment of the applicable STARTED profile. The user ID does not need to have any non-standard attributes.
  5. Copy the STC procedure to your STC proclib.
    The example CKXLOG procedure must be available in one of the system STC proclibs. Copy and adapt the CKXLOG procedure from the SCKRPROC library.
  6. Authorize the STC user ID to allocate and write the log stream.
    The CKXLOG started task writes record to the specified log stream. If the log stream does not exist, it defines the log stream. For these actions, the STC user ID needs sufficient authorization. Use the following table for the required authorization:
    Table 1. Authorization of the STC user ID
    Action Type of log stream Required authorization Resource class Resource name
    DEFINE DASDONLY ALTER LOGSTRM log_stream_name
    COUPLING FACILTY ALTER LOGSTRM log_stream_name
    UPDATE FACILITY IXLSTR.model_structure_name
    CONNECT   UPDATE LOGSTRM log_stream_name
  7. Start the CKXLOG started task.
    The zSecure Admin Command Logger task is started from the operator console by a START command. The command executes the procedure from the applicable system proclib. It is possible to specify startup parameters. These parameters can be given at the START command itself. An example of such a START command is:
    S CKXLOG,,,DEBUG
    The following START parameters are supported:
    DEBUG
    Specifies that diagnostic messages must be issued during startup and running of the CKXLOG task. This setting is in effect until a subsequent NODEBUG command is issued from the operator console.
    FORCE
    Specifies that, regardless of a previous execution, initialization must continue. Only use the FORCE option if you cannot start the zSecure Command Logger normally. The FORCE option might enable starting the zSecure Command Logger without the need to IPL the system. During normal operation, the FORCE option is never required.
    DEBUG-FORCE
    Specifies that both the DEBUG and FORCE options must be active at startup.
    To terminate the started task, the console operator can issue the STOP command. z/OS supports the use of the P command as an alias of the STOP command; for example:
    P CKXLOG
    The STOP command can also be issued as the parameter on the MODIFY command. z/OS supports use of the F command as an alias of the MODIFY command. An example of such a command is:
    F CKXLOG,STOP
    While the CKXLOG started task is active, the console operator can also issue commands to modify the zSecure Command Logger. These commands can be issued through the MODIFY console command. For example:
    MODIFY CKXLOG,DEBUG
    The following list describes the zSecure Command Logger operator commands that can be used in the MODIFY console command:
    ABND
    This command causes an immediate abend of the CKXLOG started task, with recovery. It is intended for IBM® internal testing only.
    CRSH
    This command causes an immediate abend of the CKXLOG started task, without any recovery. It is intended for IBM internal testing only.
    DEBUG
    This command controls the diagnostic and monitoring messages that the program can generate; the zSecure Messages Guide describes all messages. The command is effective immediately. The DEBUG command does not support any additional keywords.
    NODEBUG
    Deactivates issuing of diagnostic and monitoring messages. The NODEBUG command does not support any additional keywords.
    SIPL
    This command is used during the migration to a new release. It results in freeing all in-memory data structures, loss of a system level linkage index (LX), and marking the address space as non-reusable. System level LX's are a limited resource and cannot be recovered without an IPL of the system. When upgrading from one release of the zSecure Command Logger to another, the installation instructions require that you shut down the previous version using this SIPL command. The SIPL command does not support any additional keywords.
    STOP
    Stop execution of the zSecure Command Logger started task. This results in an orderly shutdown of the task. Some memory remains reserved after termination of the task, to enable reuse of some critical system resources during a subsequent restart of the started task. The effect of the STOP MODIFY command is identical to that of the z/OS STOP command. The STOP command does not support any additional keywords.
  8. Define the Command Log policies for zSecure components.
    The zSecure Admin Command Logger checks if commands that are issued through supported zSecure components must be logged. In the absence of any profile, commands are not logged. To activate command logging, you must define one or more profiles in the XFACILIT class. These switch profiles have the following format: CKX.CKXLOG.LOG.component-name, where component-name can be one of the following options:
    CKRCARLA
    The zSecure common program.
    CKXI
    zSecure Admin Command Execution module CKX. This is used for queued commands and for commands that are issued through the zSecure Server.
    CKGRACF
    The zSecure Admin RACF special functions program.
    C4RMAIN
    zSecure Command Verifier.
    CKXLOGID
    Special logging program when testing the LOG function of the Command Logger.
    You can use a generic profile to match these various component names.
    When commands are issued using the zSecure Admin interface, the same command can be logged multiple times, because it passes multiple components. By defining these profiles, you can control for which components the commands must be logged and for which components logging the commands must be suppressed. In the absence of any profile, commands are not logged. To activate logging, the user that issues the command must have at least READ access to the resource, for example:
    CKX.CKXLOG.LOG.*   ID(*)    ACCESS(READ)
  9. Configure the zSecure Admin ISPF user interface for command logging.
    Command logging from the zSecure Admin ISPF panels is enabled by defining a profile CKR.CKXLOG.**. Individual functions related to command logging can be controlled by also creating more specific profiles as described in subsequent paragraphs. Creating this CKR.CKXLOG.** profile with UACC(READ), and not defining more specific profiles, changes the command confirmation level (as specified in SE.4) for all zSecure Admin users, and enforces that a ticket ID and description are entered for every generated command.

    To allow users to specify ticket information, the following resource is used: CKR.CKXLOG.ID.SHOW. Users with at least READ access to the matching XFACILIT profile can use the CKXLOGID primary ISPF command and can specify or confirm ticket information during command confirmation. Command confirmation is active according to the user specified setting in SETUP CONFIRM (SE.4). The matching profile for this resource can be generic, for example the CKR.CKXLOG.** profile.

    To require that a user fills in the ticket ID and description, the following resource is used: CKR.CKXLOG.ID.PROMPT. Users with at least READ access to the matching XFACILIT profile always see a command confirmation panel when commands are generated, irrespective of the value that is specified in SETUP CONFIRM (SE.4 or SE.D.4). They must supply ticket information for the generated commands, optionally through the CKXLOGID primary ISPF command. The matching profile for this resource can also be generic, for example the CKR.CKXLOG.** profile. It is expected that most organizations will define a discrete profile with UACC(NONE) and will not require all users to specify or confirm the ticket ID and description for every generated command.

    Note: Additional logging of RACF commands can be provided by zSecure Command Verifier, independent of the command logging functions of zSecure Admin. See the step 10 for setup instructions. Installations can decide to log through the zSecure Admin interface, through zSecure Command Verifier, or through both logging mechanisms. Logging is finally controlled by the user's access to CKX.CKXLOG.component profiles, as described in step 8.
  10. Configure zSecure Command Verifier to ensure logging of commands that are issued in a batch job or from outside the zSecure Admin ISPF interface.
    You can use zSecure Command Verifier to record most RACF commands. To activate this function, you must define one or more profiles in the XFACILITY class. The profiles have the following format: C4R.command.=CKXLOG, where command is the unabbreviated RACF command. Generics can be used, except for the =CKXLOG qualifier, which must be present exactly as shown. zSecure Command Verifier logs all RACF commands through the zSecure Admin Command Logger for users that have at least READ access to the applicable profile. To suppress warning messages due to missing ticket information, or an inactive CKXLOG server, users must have at least UPDATE access to the C4R.command.=CKXLOG resource.

    For more information about zSecure Command Verifier, see zSecure Command Verifier User Guide.

  11. Optional: Enable calling CKXLOGID from APF environment.
    The CKXLOGID command is a regular TSO command that does not need APF authorization. However, if it is invoked from inside an APF-authorized program, additional definitions are required. If you plan to create your own APF-authorized program that calls CKXLOGID through the TSO service route IKJEFTSR, then you must add CKXLOGID to the list of APF-authorized commands (AUTHCMD) in the active TSO parmlib member (IKJTSOnn). If you do not plan to write such a program, no further action is required, and you can skip this step.