Configuring the audit interceptor

You can use the audit interceptor that is included with IBM® z/OS® Connect to write SMF 123 records, which contain data that can be used to audit and analyze requests.

CAUTION:

SMF 123 version 2 records are not a compatible extension of the version 1 records. Therefore, before you select version 2 of the records, check that the tools you use to format SMF 123 records support the version 2 format.

Enabling recording of SMF 123 records

To generate SMF 123 records, you must include record type 123 in your SMF configuration options or the __smf_record function fails with return code JRSMFNotAccepting (0x406). For example, include "123" in your SYS(TYPE(...,123,...)) statement, in PARMLIB. For more information, see Statements and parameters for SMFPRMxx.

Note: For IBM z/OS Connect to write to SMF, the user ID under which IBM z/OS Connect runs, must have READ access to the RACF® BPX.SMF profile of the FACILITY class. For example,

PERMIT BPX.SMF CLASS(FACILITY) ACCESS(READ) ID(USERID)

For more information, see Defining z/OS UNIX users to RACF in the z/OS UNIX System Services Planning documentation.

Configuring the audit interceptor

By default, the audit interceptor writes SMF subtype 1 version 1 records. You can set the apiProviderSmfVersion or apiRequesterSmfVersion attributes to 2 to record version 2 records for API provider and API requester respectively. All administration requests are treated as API provider requests and are therefore controlled by the apiProviderSmfVersion attribute. You can enable the audit interceptor globally for the IBM z/OS Connect server or specifically for individual APIs, services, and API requesters.

Note: If the audit interceptor is enabled both globally and specifically on an individual API, service, or API requester, then two SMF 123 records are written for that request, unless the runGlobalInterceptors attribute is set to false on the relevant specific definition.

The following example shows how to enable the audit interceptor globally to capture records SMF 123 version 2 records for all API provider, API requester, and administration requests:


<!-- Audit interceptor configuration -->
<zosconnect_auditInterceptor id="auditInterceptor" sequence="1" apiProviderSmfVersion="2" apiRequesterSmfVersion="2"/>

<!-- Interceptor list configuration -->
<zosconnect_zosConnectInterceptors id="interceptorList1" interceptorRef="auditInterceptor"/>

<!-- Enable audit interceptor globally -->
<zosconnect_zosConnectManager globalInterceptorsRef="interceptorList1"/>

The following example shows how to enable the audit interceptor for a specific API, service, or API requester:


<!-- Enable interceptor for API "myAPI" -->   
<zosconnect_zosConnectAPIs>
       <zosConnectAPI name="myAPI" interceptorsRef="interceptorList1"/>
</zosconnect_zosConnectAPIs> 

<!-- Enable interceptor for service "myService" -->
<zosconnect_services>
    <service name="myService" interceptorsRef="interceptorList1"/>
</zosconnect_services>    

<!-- Enable the interceptor for API Requester myAPIrequester -->
<zosconnect_apiRequesters>
   <apiRequester name="myAPIrequester" interceptorsRef="interceptorList1"/>   
</zosconnect_apiRequesters>

Configuring interceptor sequence

Use the sequence parameter to control the sequence in which interceptors are called. For more information, see Configuring interceptors.

Capturing request and response headers in SMF data

If you set apiProviderSmfVersion or apiRequesterSmfVersion to 2, then it is possible to capture request and response headers for a specific request. For API provider, only response headers that are defined in response data mapping can be captured. For more information, see Defining and mapping headers, query parameters, or path parameters. The following example shows how to specify a comma-separated list of three request header names and two response header names. A maximum of four header names can be specified for each. Replace the header names in this example with the names of the headers whose values that you want to capture:

<zosconnect_auditInterceptor id="interceptorList1" sequence="1" apiProviderSmfVersion="2" apiRequesterSmfVersion="2"

apiProviderRequestHeaders="Request-Name-1, Request-Name-2, Request-Name-3" 
apiProviderResponseHeaders="Response-Name-1, Response-Name-2"

apiRequesterRequestHeaders="Request-Name-A, Request-Name-B, Request-Name-C" 
apiRequesterResponseHeaders="Response-Name-A, Response-Name-B"/>

If each specified header is present on the request or response, the header name and header value are stored in the relevant field of the SMF record: SMF123Sn_REQ_HDRn or SMF123Sn_RESP_HDRn in the following format:

<headerName>:<headerValue>

For more information, see zosconnect_auditInterceptor in the Reference section of this documentation.

Reducing the delay in writing SMF V2 records

By default, the audit interceptor writes SMF 123 V2 records when the maximum number of requests that can fit into a single SMF record is reached. This is ideal for systems that run with a high workload as the maximum number is reached quickly. However, for low workload systems such as in test and development, this might not be ideal as request data might take a long time to be written to SMF. Therefore, from 3.0.58, you can use the apiProviderMaxDelay and apiRequesterMaxDelay attributes on the audit interceptor to reduce the delay in writing the SMF 123 V2 records to SMF.

The following example shows how to configure the audit interceptor to write API provider SMF 123 subtype 1 version 2 records after a maximum of 5 seconds delay and API requester SMF 123 subtype 2 version 2 records after a maximum of 1 minute delay:

<zosconnect_auditInterceptor id="interceptorList1" sequence="1" apiProviderSmfVersion="2" apiRequesterSmfVersion="2"
apiProviderMaxDelay="5s" 
apiRequesterMaxDelay="1m"/>

If the time value is set to 0 or less than 1 second, then no delay occurs and an SMF V2 record is written for each request. The default value is -1 which means that the audit interceptor waits for the maximum number of requests to be processed before it writes the SMF V2 records.

For more information, see zosconnect_auditInterceptor in the Reference section of this documentation.

Capturing SMF records for failures in early processing

From 3.0.58, if you set apiProviderEarlyFailure or apiRequesterEarlyFailure to true, then the audit interceptor captures data for requests that fail early in processing, for example authentication failures (401) or URI failures (404). This data can be used to monitor requests that do not complete their processing and might indicate a problem that requires further investigation. The following example shows how to configure API provider and API requester to capture request data for early failures:

<zosconnect_auditInterceptor id="interceptorList1" sequence="1" apiProviderSmfVersion="2" apiRequesterSmfVersion="2"
apiProviderEarlyFailure="true" 
apiRequesterEarlyFailure="true"/>

For more information, see zosconnect_auditInterceptor in the Reference section of this documentation.