Customizing the agent by using agent parameter keywords

Use agent parameter keywords to customize the agent. The agent configuration file provides the parameters that can be customized. The parameters that do not have a default value must be specified before you start the agent started task.

How to use the agent parameters

  • Use the AUICONFG DD statement to reference these parameters with the agent JCL (AUIASTC) and Memory Management secondary address space JCL (AUIUSTC).
  • The AUICONFG DD can be used in other agent secondary address space JCLs (AUIFSTC and AUILSTC).
  • Define the data set (DSORG=PS) or data set member (DSORG=PDS|PDS/E) that contains these parameters as RECFM=FB LREL=80.
  • Specify only one keyword and parameter per line.
  • An asterisk (*) or hyphen (-) in column one indicates that the line is a comment.
  • Characters in column 72 and beyond are ignored.

Required parameters

The following parameters must be manually configured:
  • APPLIANCE_SERVER
  • LOG_STREAM_DLIB
  • LOG_STREAM_DLIO
  • SMF_DSN_MASK
  • SMF_SPILL_FILE

All available agent parameters

ADS_SHM_ID
Required: No
Default: None
Description: This keyword is optional when only one agent exists in a sysplex environment. If more than one agent exists, the configuration file for each agent should have this keyword specified with a unique integer with a value of 100000 - 999999 specified as its parameter. This keyword identifies a shared memory segment that is specific to each agent.
Note:
  • This keyword must be used in combination with ADS_LISTENER_PORT.
  • If you specify this keyword, you must add an //AUICONFG DD statement to the AUIFSTC and AUILSTC address space JCLs. This DD statement should point to the same data set and member as the agent AUIASTC and AUIUSTC JCLs to enable communication between all participating address spaces.
Syntax: ADS_SHM_ID(Shared_Memory_label)
Example: ADS_SHM_ID(100010)
ADS_LISTENER_PORT
Required: No
Default: 39987
Description: This keyword is optional when only one agent exists in a sysplex environment. If more than one agent exists, the configuration file for each agent should have this keyword specified with a unique port number specified. This keyword identifies an agent-specific communications port between the agent (AUIASTC) and the agent secondary address spaces (AUIFSTC, AUILSTC). Valid port numbers are 1 - 65535. Check with your network administrator for a list of ports available for this use.
Note:
  • This keyword must be used in combination with ADS_SHM_ID.
  • If you specify this keyword, you must add an //AUICONFG DD statement to the AUIFSTC and AUILSTC address space JCLs. This DD statement should point to the same data set and member as the agent AUIASTC and AUIUSTC JCLs to enable communication between all participating address spaces.
Syntax: ADS_LISTENER_PORT(port_number)
Example: ADS_LISTENER_PORT(16055)
APPLIANCE_SERVER
Required: Yes
Default: None
Description: The host name or IP address (in dotted decimal notation, for example: 1.2.3.4) of the IBM Security Guardium system to which the agent (AUIASTC) should connect.
Note: This parameter must be correctly configured to enable a connection to the IBM Security Guardium system. This value can contain up to 128 characters.
Syntax: APPLIANCE_SERVER(hostname|IP_address)
Example: 

APPLIANCE_SERVER(wal-vm-guardium20)
APPLIANCE_SERVER(192.168.2.205)
APPLIANCE_SERVER_[1-5]
Required: No
Default: None
Description: Enables alternative host names or TCP/IP addresses to be used for multistream Guardium appliance destinations or failover recovery processing. Up to five alternative host names or TCP/IP addresses are supported.
To specify one or more entries, include this parameter with a numeric suffix from 1 - 5. Provide a unique host name or TCP/IP address for each entry.
Valid values are any valid host name or TCP/IP address.
Note:
  • The use of this keyword does not eliminate the need for the APPLIANCE_SERVER keyword.
  • The APPLIANCE_SERVER_LIST parameter designates how this parameter is used.
  • If used in combination, this parameter overrides the APPLIANCE _SERVER_[MULTI_STREAM|FAILOVER|HOT_FAILOVER]_[1-5] parameter.
Syntax: 
APPLIANCE_SERVER_n(hostname|IP_addr)
where n can be 1, 2, 3, 4, or 5.
Example:

APPLIANCE_SERVER_1(nwt-vm-guardium3)
APPLIANCE_SERVER_1(192.168.2.205)
APPLIANCE_SERVER_[MULTI_STREAM|FAILOVER|HOT_FAILOVER]_[1-5]
Required: No
Default: None
Description: The host name or IP address (in dotted decimal notation, for example: 1.2.3.4) of the IBM Security Guardium system for the IBM Security Guardium S-TAP for IMS agent to use to stream to multiple Guardium appliance destinations or for failover processing. This value can contain up to 128 characters.
Note:
  • The use of this keyword does not eliminate the need for the APPLIANCE_SERVER keyword.
  • If this parameter, or the APPLIANCE_SERVER_[1-5] parameter, is not detected at startup, then neither failover nor hot failover processing is activated.
  • The APPLIANCE_SERVER_LIST parameter designates how this parameter is used.
  • If used in combination, this parameter is overridden by the APPLIANCE_SERVER_[1-5] parameter.
Syntax: 
APPLIANCE_SERVER_[MULTI_STREAM|FAILOVER|HOT_FAILOVER]_n(hostname|IP_address)
where n can be 1, 2, 3, 4, or 5.
Example: 

APPLIANCE_SERVER_MULTI_STREAM_1(wal-vm-guardium20)
APPLIANCE_SERVER_FAILOVER_1(nwt-vm-guardium8)
APPLIANCE_SERVER_HOT_FAILOVER_1(wal-vm-guardium16)
APPLIANCE_SERVER_MULTI_STREAM_1(192.168.2.201)
APPLIANCE_SERVER_FAILOVER_1(192.168.2.202)
APPLIANCE_SERVER_HOT_FAILOVER_1(192.168.2.203)
APPLIANCE_SERVER_LIST(MULTI_STREAM|FAILOVER|HOT_FAILOVER)
Required: No
Default: FAILOVER
Description: Set APPLIANCE_SERVER_LIST to MULTI_STREAM for a Guardium appliance connection to be established for each server that is identified by the APPLIANCE_SERVER_MULTI_STREAM_n parameter.
  • If a connection is lost, S-TAP audit events continue to transmit over the remaining appliance connection.
  • Lost connections are retried at regular intervals that are determined by multiplying the APPLIANCE_CONNECT_RETRY_COUNT by the APPLIANCE_PING_RATE.
Set APPLIANCE_SERVER_LIST to FAILOVER for one Guardium appliance connection to be active at a time.
  • If the connection to the primary appliance is lost, a failover action occurs, which results in an attempt to connect to the next available server. The next available server is identified by the APPLIANCE_SERVER_FAILOVER_n parameter. The agent attempts to connect to subsequent Guardium systems, beginning with APPLIANCE_SERVER_FAILOVER_1 and ending with APPLIANCE_SERVER_FAILOVER_5.
  • After a failover action occurs, the connection to the primary server is retried at regular intervals that are determined by multiplying the APPLIANCE_CONNECT_RETRY_COUNT by the APPLIANCE_PING_RATE.
Set APPLIANCE_SERVER_LIST to HOT_FAILOVER to cause connection types for each connected Guardium appliance identified by the APPLIANCE_SERVER_HOT_FAILOVER_n parameter to be kept active by pings.
  • You must specify the primary Guardium appliance by using the APPLIANCE_SERVER parameter.
  • If the primary Guardium appliance becomes unavailable and failover occurs, HOT_FAILOVER maintains the activity of the primary appliance policy.
With any setting of APPLIANCE_SERVER_LIST, if all connections fail, and a spill file is specified (parameter OUTAGE_SPILL_AREA_SIZE), events are buffered to the spill file until a connection becomes available. If no spill file is specified, and all connections are lost, data loss occurs.
The default is FAILOVER.
APPLIANCE_PORT
Required: No
Default: 16022
Valid ports: 16022 or 16023
Description: The IP port number of the IBM Security Guardium system to which the IBM Security Guardium S-TAP for IMS agent should connect. This parameter must be correctly configured to enable a connection to the IBM Security Guardium system. If port 16023 is used, encryption support is required for the connection to the appliance.
Note: Specifying this keyword and parameter designates the port on which the IBM Security Guardium system is listening to the S-TAP. The port is dedicated to the IP address of the appliance. Port 16022 or 16023 can also be in use on z/OS by another application.
Syntax: APPLIANCE_PORT(port_number)
Example: APPLIANCE_PORT(16022)
APPLIANCE_PING_RATE
Required: No
Default: 5
Description: Specifies the interval time between accesses to the IBM Security Guardium system to prevent timeout disconnections during idle periods. The value is in number of seconds.
Syntax: APPLIANCE_PING_RATE(ping_interval)
Example: APPLIANCE_PING_RATE(5)
APPLIANCE_NETWORKDB_PSB_REQUEST_TIMEOUT
Required: No
Default: 500
Description: Specifies a value in milliseconds of time to wait for the completion of a network communication request to send or receive. A value of 0 results in no timeout period. Range: 0 or 500 - 12000.
Syntax: APPLIANCE_NETWORK_REQUEST_TIMEOUT(milliseconds)
Example: APPLIANCE_NETWORK_REQUEST_TIMEOUT(500)
AUIAOE00_EXIT(Y|N)
Required: No
Default: N
Description: Enables the IMS Type-2 AOIE exit AUIAOE00 for auditing of IMS DBR commands. Use in conjunction with IMSL_CYCLE_INTERVAL and IMSL_AUDIT_LEVELS.
Syntax: AUIAOE00_EXIT(Y|N)
Example: AUIAOE00_EXIT(N)
AUIU_EXCLUDE_LPAR
Required: No
Default: None
Description: Specifies a list of LPAR names (one to eight characters) in a SYSPLEX environment where the Common Storage Management Utility (AUIUSTC) should not be scheduled. Multiple AUIU_EXCLUDE_LPAR statements can be specified to allow for LPAR name strings that are longer than 53 bytes.
Note: Use this keyword with caution. DLI calls run on the excluded LPARS are not audited.
With the exception of the LPAR where the agent resides, all LPARS can be excluded by using the option *ALL in place of an LPAR name.
Syntax: AUIU_EXCLUDE_LPAR(list_of_lpars)
Example: AUIU_EXCLUDE_LPAR(RS21,MYLPAR,YOURLPAR) or AUIU_EXCLUDE_LPAR(*ALL)
AUIU_PROC_NAME
Required: No
Default: AUIUSTC
Description: Specifies the PROCLIB member name that contains the Common Storage Management Utility JCL. This JCL is supplied as member name AUIUSTC in the sample library (AUISAMP). If multiple agents are used within a sysplex, each agent requires a separate JCL for each AUIUSTC address space.
Syntax: AUIU_PROC_NAME(auiu_mbr_name)
Example: AUIU_PROC_NAME(AUIUV1013)
DISPLAY_IMSMSG_DLIB(Y|N)
Required: No
Default: N
Description: Controls the output of informational messages AUIJ255I, AUIJ256I, AUIJ257I, and AUIJ258I in the AUILOG output DD of the AUIASTC agent address space. These messages are generated from data that is produced by the IMS DLI/DB batch jobs, and is passed to the agent from the DLIB z/OS log stream.

The default setting, N, prevents these messages from being written to the AUILOG DD.

Specify Y for these messages to be written to the AUILOG DD.

Syntax: DISPLAY_IMSMSG_DLIB(Y|N)
Example: DISPLAY_IMSMSG_DLIB(Y)
DISPLAY_IMSMSG_DLIO(Y|N)
Required: No
Default: N
Description: Controls the output of informational messages AUIJ255I, AUIJ256I, AUIJ257I, and AUIJ258I in the AUILOG output DD of the AUIASTC agent address space. These messages are generated from data that is produced by the IMS Control Region and passed to the agent from the DLIO z/OS log stream.

The default setting, N, prevents these messages from being written to the AUILOG DD.

Specify Y for these messages to be written to the AUILOG DD.

Syntax: DISPLAY_IMSMSG_DLIO(Y|N)
Example: DISPLAY_IMSMSG_DLIO(Y)
DLIFREQ
Required: No
Default: 100K
Description: Enables you to customize the number of DLI calls that are sent to the Guardium appliance before message AUIJ012I (providing a count of the number of events sent to appliance) is issued.

The count can be represented in thousands (K) or millions (M). Valid values are 10K – 999K and 1 – 10M.

Syntax: DLIFREQ(100K)
Example: DLIFREQ(100K)
FORCE_LOG_LIMITED
Required: No
Default: N
Description: Enables you to force limited audit logging by removing sensitive information (such as IMS segment data and concatenated key values) from data that is sent to the Guardium appliance by the S-TAP.

Specify Y to restrict sensitive data from being sent to the Guardium appliance.

Syntax: FORCE_LOG_LIMITED(Y|N)
Example: FORCE_LOG_LIMITED(N)
IMSL_AUDIT_LEVELS
Required: No
Default: ALL
Description: Specifies the events to be audited from those that are found using the IMS Archive Log task (AUILSTC) for each IMS instance under control of this agent. A specification other than ALL limits auditing to the events you specify.

For example, if you specify USERS, then all audited IMS instances under the agent report user signons and signoffs. If you specify ALL, you can use the Guardium interface to specify further limitations on what is audited for each audited IMS subsystem.

Table 1. IMSL_AUDIT_LEVELS audit parameters and events.
Parameter Audited event
ALL All events are audited (default)
CTL_STRT IMS control region stops and starts
USERS User sign-on and sign-off
DBOPN Database opens and closes
DB_PSB DBR, DBDDUMP, DB/PSB START/STOP/LOCK/UNLOCK
Syntax: IMSL_AUDIT_LEVELS(ALL|CTL_STRT|USERS|DBOPN|DB_PSB)
Example: IMSL_AUDIT_LEVELS(ALL)
IMSL_CYCLE_INTERVAL
Required: No
Default: 15
Description: Specifies the frequency (in minutes) that the IMS Archive Log task (AUILSTC) checks the RECON data sets for new IMS System Log Data Sets (SLDS) to process. This value should correspond to the frequency at which IMS generates SLDS data sets during a normal workload. For example, if IMS SLDS are produced every 20 minutes, the IMSL_CYCLE_INTERVAL should be set to 20. You can specify a value of 0 (zero):
  • to instruct the agent to not start the AUILSTC task for any IMS subsystem that the agent controls
  • to prevent the auditing of IMS DBR commands for any IMS subsystem the agent controls
Valid parameters are 0 – 1440.
Syntax: IMSL_CYCLE_INTERVAL(time_in_minutes)
Example: IMSL_CYCLE_INTERVAL(45)
IMSL_ID_PREFIX
Required: No
Default: None
Description: Allows the partial customization of the 8-byte ID that is used when starting the AUILSTC task.
When this keyword is not used, the string AAAAAAAA is used for the first AUILSTC task to be started. Subsequent started AUILSTC tasks cause the ALPHA string to be incrementally increased by one character until the value of ZZZZZZZZ is reached. When ZZZZZZZZ is reached, the string is reset to AAAAAAAA when the agent (AUIASTC) is stopped and restarted.
When this keyword is used, the specified prefix (up to 6 bytes) is used, while the remaining two to seven characters are incrementally increased in the manner previously described. This enables a constant value (the specified prefix) to be used, alongside a wildcard character, when you are defining the ID to the TCP/IP security package to permit access to TCP/IP ports.
Note: The first character of the keyword must be an alphabetic character.
Syntax: IMSL_ID_PREFIX(your_prefix)
Example: IMSL_ID_PREFIX(MYPFX)
The example IMSL_ID_PREFIX(MYPFX) results in a generated AUILSTC ID of MYPFXAAA -- MYPFXZZZ.
IMSL_PROC_NAME
Required: No
Default: AUILSTC
Description: Specifies the PROCLIB member name that contains the IMS Archive Log JCL. This JCL is supplied as member name AUILSTC in the sample library (AUISAMP). If multiple agents are used within a sysplex, each agent requires a separate JCL for each AUILSTC address space.
Syntax: IMSL_PROC_NAME(auil_mbr_name)
Example: IMSL_PROC_NAME(AUILV1013)
IMSL_SLDS_SRCH
Required: No
Default: 30
Description: This keyword can be used to limit the number of days within which the IMS log reader (AUILxxxx) will search for IMS system log data sets (SLDS) to process.
  • If an IMS checkpoint does not exist for the SLDS reader, AUILxxxx will search for IMS SLDS that were created on the current day and for x days prior to the current day (where x is the value that you set for this parameter).
  • If an IMS checkpoint that is set for the SLDS reader exceeds the number of days between the current day and the value that you set for this parameter, then the IMS checkpoint will be used as the starting point for IMS SLDS to be read and processed.
  • If you set a value of 0 (zero) for this parameter, then only the current day's IMS SLDS will be processed. Also, IMS SLDS that were migrated from a hierarchical storage manager product will not be recalled for processing.
    Note: If you set a value of 0 (zero) for this parameter, AUILxxxx processing will omit any IMS SLDS that were created on the previous day. This can cause data to be missed if, for example, the AUILxxxx task is run at 12:05 AM. IMS SLDS that were created prior to midnight will not be recognized as being within the current day, and thus will not be processed.
Syntax: IMSL_SLDS_SRCH(number_of_days)
Example: IMSL_SLDS_SRCH(15)
LOG_FILTER(I/E)
Required: No
Default: I (include)
Description: Specifies whether to include or exclude messages that have been specified by the LOG_FILTER_MSG_ID parameter.
  • The default value, I, allows only the specified message IDs to be included in the AUILOG output stream. Message IDs that are not specified by the LOG_FILTER_MSG_ID(messages) parameter will be suppressed. The default value should be used unless there is a specific business need to suppress messages.
  • The optional value, E, suppresses the specified message IDs from the AUILOG output stream.
    Tip: The E value should only be used if the LOG_FILTER_MSG_ID keyword has been customized to suppress specific messages. Do not use the optional value (E) in conjunction with LOG_FILTER_MSG_ID(*) unless you want to prevent all messages from being written to the AUILOG output stream. Suppressing all messages is not recommended.
Syntax: LOG_FILTER(include/exclude)
Example: LOG_FILTER(E)
LOG_FILTER_MSG_ID(messages)
Required: No
Default: * (all messages)
Description: Can be used in conjunction with the LOG_FILTER(I/E) parameter to suppress specific messages from being written to the AUILOG output stream.
Tip: The LOG_FILTER_MSG_ID(*) default value should only be used with the LOG_FILTER(I) default value. Do not specify LOG_FILTER(E) in conjunction with LOG_FILTER_MSG_ID(*) unless you want to prevent all messages from being written to the AUILOG output stream. Suppressing all messages is not recommended.
Syntax: LOG_FILTER_MSG_ID(id1,id2,id3...)
Example: LOG_FILTER_MSG_ID(AUIZ014W)
LOG_PORT_SCAN_START
Required: No
Default: 41500
Description: Specifies the first communications port number to be checked for availability to be used for internal message logging communications. Use this keyword if environmental conditions dictate that a sequential scan and test of ports from port numbers 41500 - 65535 should not be performed. You can override the starting port with a port of your choice. This keyword and parameter can be used with the LOG_PORT_SCAN_COUNT keyword to limit the ports that are scanned to a specific range.
Syntax: LOG_PORT_SCAN_START(port_number)
Example: LOG_PORT_SCAN_START(41500)
LOG_PORT_SCAN_COUNT
Required: No
Default: 10
Description: This keyword can be used in conjunction with the LOG_PORT_SCAN_START keyword to limit number of the ports that are scanned and tested for availability. The integer specified (1 - 65535) represents the number of ports that should be scanned. If the port number specified by the LOG_PORT_SCAN_START value plus the LOG_PORT_SCAN_COUNT value exceeds 65535, the scan terminates at port 65535.
Syntax: LOG_PORT_SCAN_COUNT(number_of_ports)
Example: LOG_PORT_SCAN_COUNT(1000)
LOG_STREAM_DLIB
Required: Yes
Default: None
Description: This required keyword is used to specify the z/OS System Logger log stream to stream audited events from DLI DBB batch jobs. The value should be the BATCH_LOGSTREAM_NAME value specified as the DEFINE LOGSTREAM NAME parameter of the AUILSTR2 or AUILSTR3 JCLs.
Syntax: LOG_STREAM_DLIB(log_stream_name)
Example: LOG_STREAM_DLIB(AUI_BATCH_LOG_STREAM)
LOG_STREAM_DLIO
Required: Yes
Default: None
Description: This required keyword is used to specify the z/OS System Logger log stream to be used to stream audited events from IMS Control Regions. The value should be the ONLINE_LOGSTREAM_NAME value specified as the DEFINE_LOGSTREAM_NAME parameter of the AUILSTR2 or AUILSTR3 JCLs.
Syntax: LOG_STREAM_DLIO(log_stream_name)
Example: LOG_STREAM_DLIO(AUI_ONLINE_LOG_STREAM)
LOOPBACK_ADDRESS
Required: No
Default: LOCALHOST
Description: Specifies the loopback host or IP address that is used for communications between the agent and the agent secondary address spaces. For most network configurations, the default value of LOCALHOST can be used. If LOCALHOST cannot be resolved on your system, consult your network specialist for the correct loopback mnemonic or IP address to be used.
Syntax: LOOPBACK_ADDRESS(hostname|IP_address)
Example: LOOPBACK_ADDRESS(LOCALHOST)
LPAR_MONITOR_INTERVAL
Required: No
Default: 5
Description: Specifies the frequency (in minutes) for the agent to request a list of LPARs that are active within the SYSPLEX. Schedule the Common Storage Management Utility (AUIUSTC) tasks on any LPAR coming online to the SYSPLEX. Valid parameters are integers between 1 and 60.
Syntax: LPAR_MONITOR_INTERVAL(minutes)
Example: LPAR_MONITOR_INTERVAL(5)
MESSAGE_LOG_LEVEL
Required: No
Default: I
Description: Controls the amount of output log information that is generated by the agent.
Table 2. Message severity codes and descriptions.
Message severity code Description
I Includes all log messages
W Includes all log messages with a warning severity or higher
E Includes all log messages with an error severity or higher
O Instructs the agent not to log error messages
S Includes all log messages with a severe error code
Syntax: MESSAGE_LOG_LEVEL(I|W|E|O|S)
Example: MESSAGE_LOG_LEVEL(I)
OUTAGE_SPILL_AREA_SIZE
Required: No
Default: 0
Description: Determines the maximum amount of memory in megabytes to be allocated for the retention of audit data in the event of an IBM Security Guardium system connection outage. A value of 0, or the absence of this keyword, disables spill area support. The maximum value permitted as a parameter is 1024.
Syntax: OUTAGE_SPILL_AREA_SIZE(memory_size)
Example: OUTAGE_SPILL_AREA_SIZE(15)
POLICY_READ_INTERVAL
Required: No
Default: 5
Description: Determines the frequency in seconds that the connection to the IBM Security Guardium system checks for changes to the installed policies that are used to determine audited event collection.
Syntax: POLICY_READ_INTERVAL(time_in_seconds)
Example: POLICY_READ_INTERVAL(5)
STAP_STREAM_EVENTS
Required: No
Default: Y
Description: Specifies whether events will be streamed to the IBM Security Guardium system. The default value, Y, enables streaming. Specify N to disable streaming and enable Simulation mode.
Syntax: STAP_STREAM_EVENTS(Y|N)
Example: STAP_STREAM_EVENTS(Y)
PREFER_IPV4_STACK

Required: No

Default: N

Description: If set to Y, this parameter causes a request to be issued to the Domain Name Server (DNS) for an IPV4 address for the hostname that is specified in the APPLIANCE_SERVER parameter:
  • The DNS lookup request for an IPV4 address is attempted. If an IPV4 address is defined for the hostname, the DNS responds with the value that will be used to connect to the Guardium appliance.
  • If only an IPV6 address is defined at the DNS, then the DNS responds with the IPV6 address used to connect to the Guardium appliance.
  • If both IPV4 and IPV6 addresses are defined at the Guardium appliance, the DNS responds with both addresses, and the IPV4 address is used to connect to the appliance.
If this parameter is set to N or omitted from configuration, a request for an IPV6 address is issued to the DNS for the hostname specified by the APPLIANCE_SERVER parameter:
  • The DNS lookup request for an IPV6 address is attempted. If an IPV6 address is defined for the hostname, the DNS responds with the value used to connect to the Guardium appliance.
  • If only an IPV4 address is defined at the DNS, then the DNS responds with the IPV4 address used to connect to the Guardium appliance.
  • If both IPV4 and IPV6 addresses are defined at the Guardium appliance, the DNS responds with both addresses, and the IPV4 address is used to connect to the appliance.
Note: Whether or not this parameter is used, an invalid address for the hostname returned from the DNS results in a failure to connect to the appliance, and the IBM Security Guardium S-TAP for IMS started task will terminate.
Syntax: 
PREFER_IPV4_STACK(Y|N)
Example: 
PREFER_IVP4_STACK(Y)
SMF_AUDIT_LEVELS
Required: No
Default: ALL
Description: Specifies which events to audit of those found using the SMF task (AUIFSTC). A specification other than ALL limits the events to be audited to the events you specify. For example, if DELETE is specified, then all audited IMS instances under the agent would only be capable of reporting data set DELETE events. If ALL is specified, you can further limits what is audited for each audited IMS subsystem, using the user interface.
Table 3. SMF_AUDIT_LEVELS audit parameters and events
Parameter Audited event
ALL All events are audited (default)
UPDATE Data sets opened with UPDATE access
DELETE Data sets deleted
READ Data sets opened with READ access
CREATE Data sets created
ALTER Data sets opened with ALTER access
RACF® RACF violations on data sets
Syntax: SMF_AUDIT_LEVELS(ALL|UPDATE|DELETE|READ|CREATE|ALTER|RACF)
Example: SMF_AUDIT_LEVELS(ALL)
SMF_CYCLE_INTERVAL
Required: No
Default: 300
Description: Specifies the frequency (in minutes) that the SMF task (AUIFSTC) checks the z/OS catalog for new data sets, which meet the specified data set masks, using the SMF_DSN_MASK keyword. This value should correspond to the frequency at which your z/OS system swaps SMF logging VSAM files (sometimes known as SMF MANX|MANY) during a normal workday. For example, if the SMF logging files are swapped every 8 hours, the SMF_CYCLE_INTERVAL should be set to 480 (8 hours * 60 minutes). A value of zero can be specified to indicate that the agent should not start the AUIFSTC task and SMF auditing should not be performed. Valid parameters are 0 – 1440.
Syntax: SMF_CYCLE_INTERVAL(time_in_minutes)
Example: SMF_CYCLE_INTERVAL(45)
SMF_DSN_MASK_[1-10]
Required: Yes
Default: None
Description: At least one instance of this keyword is required (SMF_DSN_MASK_1). This keyword provides a data set mask used to query the z/OS catalog for sequential format data sets containing SMF data offloaded from the SMF log-files (MANX|MANY) using the IFASMFDP program. These sequential files can be the original files created when offloading the MANX|MANY files, or a copy of these sequential files created by customizing and running AUISMFDF and AUISMFDP jobs located in the product sample data set. In most environments, only one SMF_DSN_MASK would be specified, but up to 10 are allowed.
Table 4. Masking character rules
Character Rule
% Indicates that only one alphanumeric or national character can occupy that position
%%% Indicates that more than one character can be substituted, with the number of substitution characters being equal to the number of percent signs specified.
Example 1: specifying a GDG data set in the mask: If the AUISMFDP job has been customized to produce a GDG data set as the SORTOUT DD output data sets, you can choose to specify the fully qualified GDG base name in the mask for system name field. For example, A.B.C. IBM Security Guardium S-TAP for IMS uses catalog services to determine the names of all cataloged GDG entries under this name, for example:
  • A.B.C.G0001V00
  • A.B.C.G0002V00
  • A.B.C.G0003V00
Example 2: specifying a data set name explicitly: Provide the generation and version values as a mask. For example, A.B.C.G%%%%V%%. IBM Security Guardium S-TAP for IMS uses catalog services to determine the names of all cataloged data sets that match this mask, for example:
  • A.B.C.G0021V00
  • A.B.C.G0022V00
  • A.B.C.G0023V00
Example 3: specifying a DSN using a DATE/TIME naming convention: If you have customized the AUISMFDP job to produce a data set name that contains date and time values as qualifiers within the data set name as the SORTOUT DD output data sets, you can specify the data set name using a string of percent signs within the date and time qualifier names. For example: HLQ.D%%%%%%.T%%%%%%.SMFDATA. IBM Security Guardium S-TAP for IMS uses catalog services to determine the names of all cataloged data sets matching the mask, for example:
  • HLQ.D091122.T131000.SMFDATA
  • HLQ.D091123.T131100.SMFDATA
  • HLQ.D091124.T131200.SMFDATA
Note: The percent (%) wildcard character should only be specified for the numeric characters of the generation and version node of GDG data sets, or as the numeric characters of date or time nodes of the SMF dataset.
Syntax: SMF_DSN_MASK_1(SMF.DUMP.DSN)
Example:
SMF_DSN_MASK_1(AUI.SMF.DUMP.COPY)
SMF_DSN_MASK_2(AUI.SMF.DUMP.GDG.G%%%%V%%)
SMF_DSN_MASK_3(AUI.SMF.D%%%%%%.T%%%%%%.COPY)
SMF_EVENT_EXPIRY
Required: No
Default: 5
Description: Specifies the number of days that incomplete SMF events should be retained in the SMF spill file. Incomplete SMF events are audited events that have not yet received the associated SMF Type 30 record, which indicates that the step/job is complete, and contains information that is needed to complete the reporting of the event. When an event exceeds the expiration date, it is flagged as incomplete, sent to the IBM Security Guardium system, and removed from the SMF spill file. The valid range is 1 to 180 days.
Syntax: SMF_EVENT_EXPIRY(days)
Example: SMF_EVENT_EXPIRY(5)
SMF_PROC_NAME
Required: No
Default: AUIFSTC
Description: Specifies the PROCLIB member name that contains the SMF secondary address space JCL. This JCL is supplied as member name AUIFSTC in the sample library (AUISAMP). If multiple agents are used within a sysplex, each agent requires a separate JCL for each AUIFSTC address space.
Syntax: SMF_PROC_NAME(auif_mbr_name)\
Example: SMF_PROC_NAME(AUIFV91)
SMF_SELF_AUDIT
Required: No
Default: N
Description: Indicates whether to audit the accesses of IMS data sets that are used by the product to determine the names of IMS artifacts to be audited. Examples of IMS data sets that can be accessed include RECON data sets and IMS archived logs (SLDS). A value of N indicates that these accesses should not be audited. A value of Y indicates that these data sets should be considered for auditing.
Syntax: SMF_SELF_AUDIT(N|Y)
Example: SMF_SELF_AUDIT(N)
SMF_SPILL_FILE
Required: Yes
Default: None
Description: Specifies the DSN of a sequential format fixed block data set with a LRECL of 300. This data set is used to store incomplete audited SMF events. Incomplete audited SMF events are events triggered by SMF records that have yet to encounter an SMF Type 30 record, indicating the step or job has completed. The AUIFUSPL member of the SAUISAMP data set provides an example of the allocation specifications for this data set.
Syntax: SMF_SPILL_FILE(dsn)
Example: SMF_SPILL_FILE(AUI.V1013.SPILL)
TCPIP_BUFFER_SIZE
Required: No
Default: 32768
Description: Specifies the size of an internal buffer that is used to hold audited events in preparation of the TCP/IP send to the IBM Security Guardium system, and specifies the size of the TCP/IP buffer. In most environments, the size of this buffer should not be changed
Syntax: TCPIP_BUFFER_SIZE(buffer_size)
Example: TCPIP_BUFFER_SIZE(32768)
TRACE_CONFIG
Required: No
Default: ON
Description: TRACE_CONFIG(ON) enables IBM Guardium S-TAP for IMS configuration values to display by default at agent startup. You can optionally use this keyword to disable the IBM Security Guardium S-TAP for IMS configuration value display. To prevent the displayed report of agent configuration parameters during agent startup, specify TRACE_CONFIG(OFF).
Syntax: TRACE_CONFIG(ON|OFF)
Example: TRACE_CONFIG(OFF)
WTO_MSG
Required: No
Default: None
Description: Allows a user to request that specific informational, warning, or error messages written to the AUILOG DD statement of the agent (AUIASTC) or agent secondary address spaces (AUIFSTC, AUILSTC or AUIUSTC) also be written to the Operator Console (WTO). This enables these messages to be recognized by an automated operations tool, or provides higher operator visibility for these messages and allows appropriate action to be taken. Each message requires a separate keyword, and each keyword must be specified on a separate line.
Syntax: WTO_MSG(msgnumber)
Example: 
WTO_MSG(AUIJ011I)
WTO_MSG(AUIL607W)
WTO_MSG(AUIY006E)
XML_ECHO_AUILOG(Y|N)
Required: No
Default: N
Description: Indicates that when an audit policy is installed on an IBM Security Guardium system appliance, its corresponding XML is to be echoed to the AUILOG DD. If there is more than one policy installed on the agent, the XML of each policy is echoed. If all installed policies are subsequently uninstalled, then the echoed XML reflects that there are no installed policies. For more information about echoed XML statements, see XML statement definitions.
Syntax: XML_ECHO_AUILOG(Y|N)
Example: XML_ECHO_AUILOG(Y)
XML_ECHO_DATASET(Data_Set_Name[,Cylinders])
Required: No
Default: None
Description:

Indicates that when the IBM Security Guardium system installs an audit policy, its corresponding XML is echoed to a data set (specified by the data set name value in this parameter). If there is more than one policy installed on the agent, the XML of each is echoed. If all installed policies are subsequently uninstalled, then the echoed XML reflects that there are no installed policies. The XML will not be echoed when the installed policy is already active, is being reinstalled, and there have been no changes to the policy.

If Data_Set_Name is intended to be a Generation Data Group (GDG), then it must be set as the GDG base name. The agent checks the system catalog to determine whether Data_Set_Name exists and whether or not it is a GDG base name.

Data_Set_Name can contain z/OS system symbols such as &SYSNAME. To determine the names of the system symbols that are currently defined to the system, issue the DISPLAY SYMBOLS command to the system console.

If Data_Set_Name does not exist, and there is no GDG base defined in this name, the agent allocates the data set as non-GDG. If Data_Set_Name is a regular physical sequential data set (non-GDG based) and does exist, the agent allocates space for the Cylinders keyword when the agent is restarted.

Cylinders defaults to 1 and can range from 1 – 10.
Syntax: XML_ECHO_DATASET(&Data_Set_Name[,Cylinders])
Example: XML_ECHO_DATASET(AUIAGENT.ECHO.XML.GDG.BASE,2)
ZIIP_AGENT_DLI
Required: No
Default: N
Description: Indicates that the following agent processes should be zIIP capable: agent reads of audited events from the z/OS System Logger log streams, formatting of these events into protobuf style messages, and sending of these messages to the IBM Security Guardium system using TCP/IP.
Note: Use of the zIIP depends on the presence of a zIIP on the LPAR where the agent is running, as well as use of the Workload Management Service Policies. For more information about zIIP, see the topic on Customizing IMS to use a System z® Integrated Information Processor (zIIP).
Syntax: ZIIP_AGENT_DLI(Y|N)
Example: ZIIP_AGENT_DLI(Y)