Audit file handler

All audit events and possible outcomes are written to the audit logs when you use the audit file handler. To enable the audit file handler, add the <feature>audit-1.0</feature> element declaration inside the featureManager element in your server.xml file.

The latest information about audit logs in Liberty is available on the Open Liberty website.

Audit file handler element

The Audit 1.0 feature enables the default audit file handler implementation without the need to explicitly configure the audit file handler. By specifying only the feature itself, all supported audit events with all possible outcomes are emitted to the file-based audit log in readable format, and are not encrypted or signed. For a list of supported audit events, see Auditing Liberty events.

You can customize the audit file handler by specifying the auditFileHandler element and any of the attributes that apply to it. For more information about the attributes, see Default Audit File Handler (auditFileHandler).

Important: After the maximum number of archived audit logs is reached and the audit log file that is being written to reaches its maximum size, then the oldest archived audit log is overwritten.

Example for audit file handler with maxFiles, maxFileSize, and compact attributes specified

The following example statements for the server.xml file show the auditFileHandler element and three attributes that are specified for it.

The maxFiles attribute is set to 50, which indicates that the maximum number of archived audit logs can be 50. The maximum number of audit logs is the value of the maxFiles attribute plus an additional audit log, which is the most current audit log currently being written to.
The maxFileSize attribute is set to 100. The attribute indicates that the maximum size for an audit file is 100 MB before the audit file is archived and a new audit record is written to a new audit log file.
The compact attribute is set to true, which means that compact JSON audit records are produced.

The audit logs are written to the default ${server.output.dir}/logs directory. When the audit file is archived, new audit records are written to a new audit log file. After 50 audit logs are archived, and the current audit log being written reaches the 100-MB size, then the oldest archived audit log is overwritten.

<featureManager>
   <feature>appSecurity-2.0</feature>
   <feature>jsp-2.2</feature>
   <feature>servlet-3.1</feature>
   <feature>audit-1.0</feature>
   <feature>timedexit-1.0</feature>
</featureManager>

<auditFileHandler 
   maxFiles="50"
   maxFileSize="100"
   compact="true">
</auditFileHandler>

Event element used with the audit file handler element

To specify only those audit events and outcomes that might be of relevance in your environment, you can define within the auditFileHandler element the event element and any attributes that apply to it.

If you specify an event with only an outcome attribute and, for example, no eventName attribute, then no audit records are produced. However, if you specify an eventName attribute without an outcome attribute, all possible outcomes for that eventName are emitted.

For more information about the attributes that apply to the event element, see Default Audit File Handler (auditFileHandler).

Example for events

The following example captures security authentication events (SECURITY_AUTHN), whose outcome is success, redirect or failure; and security authorization events (SECURITY_AUTHZ) whose outcome includes all supported outcomes.

<featureManager>
   <feature>appSecurity-2.0</feature>
   <feature>servlet-4.0</feature>
   <feature>audit-1.0</feature>
</featureManager>
	
<auditFileHandler 
   maxFiles="5"
   maxFileSize="20"
   compact="true">
   <events name="AuditEvent_1" eventName="SECURITY_AUTHN" outcome="SUCCESS"/>
   <events name="AuditEvent_2" eventName="SECURITY_AUTHN" outcome="REDIRECT"/>
   <events name="AuditEvent_3" eventName="SECURITY_AUTHN" outcome="FAILURE"/>
   <events name="AuditEvent_4" eventName="SECURITY_AUTHZ"/>        
</auditFileHandler>