Audit
Audit¶
The Audit facility within the Knox Gateway introduces functionality for tracking actions that are executed by Knox per user's request or that are produced by Knox internal events like topology deploy, etc. The Knox Audit module is based on Apache log4j.
Configuration needed¶
Out of the box, the Knox Gateway includes preconfigured auditing capabilities. To change its configuration please read the following sections.
Where audit logs go¶
The Audit module is preconfigured to write audit records to the log file {GATEWAY_HOME}/log/gateway-audit.log.
This behavior can be changed in the {GATEWAY_HOME}/conf/gateway-log4j.properties file. app.audit.file can be used to change the location. The log4j.appender.auditfile.* properties can be used for further customization. For detailed information read the Apache log4j documentation.
Audit format¶
Out of the box, the audit record format is defined by org.apache.knox.gateway.audit.log4j.layout.AuditLayout.
Its structure is as follows:
EVENT_PUBLISHING_TIME ROOT_REQUEST_ID|PARENT_REQUEST_ID|REQUEST_ID|LOGGER_NAME|TARGET_SERVICE_NAME|USER_NAME|PROXY_USER_NAME|SYSTEM_USER_NAME|ACTION|RESOURCE_TYPE|RESOURCE_NAME|OUTCOME|LOGGING_MESSAGE
The audit record format can be changed by setting log4j.appender.auditfile.layout property in {GATEWAY_HOME}/conf/gateway-log4j.properties to another class that extends org.apache.log4j.Layout or its subclasses.
For detailed information read Apache log4j.
How to interpret audit log¶
| Component | Description |
|---|---|
| EVENT_PUBLISHING_TIME | Time when audit record was published. |
| ROOT_REQUEST_ID | The root request ID if this is a sub-request. Currently it is empty. |
| PARENT_REQUEST_ID | The parent request ID if this is a sub-request. Currently it is empty. |
| REQUEST_ID | A unique value representing the current, active request. If the current request id value is different from the current parent request id value then the current request id value is moved to the parent request id before it is replaced by the provided request id. If the root request id is not set it will be set with the first non-null value of either the parent request id or the passed request id. |
| LOGGER_NAME | The name of the logger |
| TARGET_SERVICE_NAME | Name of Hadoop service. Can be empty if audit record is not linked to any Hadoop service, for example, audit record for topology deployment. |
| USER_NAME | Name of user that initiated session with Knox |
| PROXY_USER_NAME | Mapped user name. For detailed information read #[Identity Assertion]. |
| SYSTEM_USER_NAME | Currently is empty. |
| ACTION | Type of action that was executed. Following actions are defined: authentication, authorization, redeploy, deploy, undeploy, identity-mapping, dispatch, access. |
| RESOURCE_TYPE | Type of resource for which action was executed. Following resource types are defined: uri, topology, principal. |
| RESOURCE_NAME | Name of resource. For resource of type topology it is name of topology. For resource of type uri it is inbound or dispatch request path. For resource of type principal it is a name of mapped user. |
| OUTCOME | Action result type. Following outcomes are defined: success, failure, unavailable. |
| LOGGING_MESSAGE | Logging message. Contains additional tracking information. |
Audit log rotation¶
Audit logging is preconfigured with org.apache.log4j.DailyRollingFileAppender.
Apache log4j contains information about other Appenders.
How to change the audit level or disable it¶
All audit messages are logged at INFO level and this behavior can't be changed.
Disabling auditing can be done by decreasing the log level for the Audit appender or setting it to OFF.