elasticsearch/x-pack/docs/en/security/auditing/overview.asciidoc

[role="xpack"]
[[auditing]]
== Auditing security events

You can enable auditing to keep track of security-related events such as
authentication failures and refused connections. Logging these events enables you
to monitor your cluster for suspicious activity and provides evidence in the
event of an attack.

[IMPORTANT]
============================================================================
Audit logs are **disabled** by default. To enable this functionality, you
must set `xpack.security.audit.enabled` to `true` in `elasticsearch.yml`.
============================================================================

The {es} {security-features} provide two ways to persist audit logs:

* The <<audit-log-output, `logfile`>> output, which persists events to
  a dedicated `<clustername>_audit.log` file on the host's file system.
  For backwards compatibility reasons, a file named `<clustername>_access.log`
  is also generated.
* The <<audit-index, `index`>> output, which persists events to an Elasticsearch
  index. The audit index can reside on the same cluster, or a separate cluster.

By default, only the `logfile` output is used when enabling auditing,
implicitly outputting to both `<clustername>_audit.log` and `<clustername>_access.log`.
To facilitate browsing and analyzing the events, you can also enable
indexing by setting `xpack.security.audit.outputs` in `elasticsearch.yml`:

[source,yaml]
----------------------------
xpack.security.audit.outputs: [ index, logfile ]
----------------------------

TIP: If you choose to enable the `index` output type, we strongly recommend that 
you still use the `logfile` output as the official record of events. If the 
target index is unavailable (for example, during a rolling upgrade), the `index` 
output can lose messages.