mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-24 23:27:25 -04:00
255c9a7f95
**Problem:** For historical reasons, source files for the Elasticsearch Guide's security, watcher, and Logstash API docs are housed in the `x-pack/docs` directory. This can confuse new contributors who expect Elasticsearch Guide docs to be located in `docs/reference`. **Solution:** - Move the security, watcher, and Logstash API doc source files to the `docs/reference` directory - Update doc snippet tests to use security Rel: https://github.com/elastic/platform-docs-team/issues/208
58 lines
3 KiB
Text
58 lines
3 KiB
Text
[role="xpack"]
|
||
[[audit-log-output]]
|
||
=== Logfile audit output
|
||
|
||
The `logfile` audit output is the only output for auditing. It writes data to
|
||
the `<clustername>_audit.json` file in the logs directory.
|
||
|
||
NOTE: If you overwrite the `log4j2.properties` and do not specify appenders for
|
||
any of the audit trails, audit events are forwarded to the root appender, which
|
||
by default points to the `elasticsearch.log` file.
|
||
|
||
[discrete]
|
||
[[audit-log-entry-format]]
|
||
=== Log entry format
|
||
|
||
The audit events are formatted as JSON documents, and each event is printed on a separate
|
||
line in the `<clustername>_audit.json` file. The entries themselves do not contain the
|
||
end-of-line delimiter.
|
||
The audit event JSON format is somewhat particular, as *most* fields follow a dotted
|
||
name syntax, are ordered, and contain non-null string values. This format creates a
|
||
structured columnar aspect, similar to a CSV, that can be more easily inspected visually
|
||
(compared to an equivalent nested JSON document).
|
||
|
||
There are however a few attributes that are exceptions to the above format. The `put`,
|
||
`delete`, `change`, `create` and `invalidate` attributes, which are only present for
|
||
events with the `event.type: "security_config_change"` attribute, contain the *nested JSON*
|
||
representation of the security change taking effect. The contents of the security config change
|
||
are hence not displayed as top-level dot-named fields in the audit event document. That's because
|
||
the fields are specific to the particular kind of security change and do not show up in
|
||
any other audit events. The benefits of a columnar format are therefore much more limited; the
|
||
space-saving benefits of the nested structure is the favoured trade-off in this case.
|
||
|
||
When the `request.body` attribute is present (see <<auditing-search-queries>>), it contains a
|
||
string value containing the full HTTP request body, escaped as per the JSON RFC 4677.
|
||
|
||
There is a list of <<audit-event-types, audit event types>> specifying the
|
||
set of fields, as well as examples, for each entry type.
|
||
|
||
[discrete]
|
||
[[audit-log-settings]]
|
||
=== Logfile output settings
|
||
|
||
The events and some other information about what gets logged can be
|
||
controlled using settings in the `elasticsearch.yml` file. See
|
||
<<event-audit-settings>> and
|
||
<<node-audit-settings>>.
|
||
|
||
IMPORTANT: Be advised that *sensitive data may be audited in plain text* when including
|
||
the request body in audit events, even though all the security APIs, such as those that
|
||
change the user’s password, have the credentials filtered out when audited.
|
||
|
||
You can also configure how the logfile is written in the `log4j2.properties`
|
||
file located in `ES_PATH_CONF` (or check out the relevant portion of
|
||
the https://github.com/elastic/elasticsearch/blob/{branch}/x-pack/plugin/core/src/main/config/log4j2.properties[log4j2.properties in the sources]).
|
||
By default, audit information is appended to the
|
||
`<clustername>_audit.json` file located in the standard Elasticsearch `logs` directory
|
||
(typically located at `$ES_HOME/logs`).
|
||
The file is also rotated and archived daily or upon reaching the 1GB file size limit.
|