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.
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.
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
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. runGlobalInterceptors
attribute is set to
false on the relevant specific definition.
<!-- 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"/>
<!-- 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
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"/>
<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.
<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
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.