[role="xpack"]
[[auditing-settings]]
=== Auditing Security Settings
++++
Auditing Settings
++++
All of these settings can be added to the `elasticsearch.yml` configuration
file. For more information, see
{xpack-ref}/auditing.html[Auditing Security Events].
[[general-audit-settings]]
==== General Auditing Settings
`xpack.security.audit.enabled`::
Set to `true` to enable auditing on the node. The default value is `false`.
`xpack.security.audit.outputs`::
Specifies where audit logs are output. For example: `[ index, logfile ]`. The
default value is `logfile`, which puts the auditing events in a dedicated
`_access.log` file on the node. You can also specify `index`, which
puts the auditing events in an {es} index that is prefixed with
`.security_audit_log`. The index can reside on the same cluster or a separate
cluster.
+
--
TIP: If the index is unavailable, it is possible for auditing events to
be lost. The `index` output type should therefore be used in conjunction with
the `logfile` output type and the latter should be the official record of events.
--
[[event-audit-settings]]
==== Audited Event Settings
The events and some other information about what gets logged can be
controlled by using the following settings:
`xpack.security.audit.logfile.events.include`::
Specifies which events to include in the auditing output. The default value is:
`access_denied, access_granted, anonymous_access_denied, authentication_failed, connection_denied, tampered_request, run_as_denied, run_as_granted`.
`xpack.security.audit.logfile.events.exclude`::
Excludes the specified events from the output. By default, no events are
excluded.
`xpack.security.audit.logfile.events.emit_request_body`::
Specifies whether to include the request body from REST requests on certain
event types such as `authentication_failed`. The default value is `false`.
+
--
IMPORTANT: No filtering is performed when auditing, so sensitive data may be
audited in plain text when including the request body in audit events.
--
[[node-audit-settings]]
==== Local Node Info Settings
`xpack.security.audit.logfile.prefix.emit_node_name`::
Specifies whether to include the node's name in the local node info. The
default value is `true`.
`xpack.security.audit.logfile.prefix.emit_node_host_address`::
Specifies whether to include the node's IP address in the local node info. The
default value is `false`.
`xpack.security.audit.logfile.prefix.emit_node_host_name`::
Specifies whether to include the node's host name in the local node info. The
default value is `false`.
[[index-audit-settings]]
==== Audit Log Indexing Configuration Settings
`xpack.security.audit.index.bulk_size`::
Controls how many audit events are batched into a single write. The default
value is `1000`.
`xpack.security.audit.index.flush_interval`::
Controls how often buffered events are flushed to the index. The default value
is `1s`.
`xpack.security.audit.index.rollover`::
Controls how often to roll over to a new index: `hourly`, `daily`, `weekly`, or
`monthly`. The default value is `daily`.
`xpack.security.audit.index.events.include`::
Specifies the audit events to be indexed. The default value is
`anonymous_access_denied, authentication_failed, realm_authentication_failed, access_granted, access_denied, tampered_request, connection_granted, connection_denied, run_as_granted, run_as_denied`.
See {xpack-ref}/audit-event-types.html[Audit Entry Types] for the
complete list.
`xpack.security.audit.index.events.exclude`::
Excludes the specified auditing events from indexing. By default, no events are
excluded.
`xpack.security.audit.index.events.emit_request_body`::
Specifies whether to include the request body from REST requests on certain
event types such as `authentication_failed`. The default value is `false`.
`xpack.security.audit.index.settings`::
Specifies settings for the indices that the events are stored in. For example,
the following configuration sets the number of shards and replicas to 1 for the
audit indices:
+
--
[source,yaml]
----------------------------
xpack.security.audit.index.settings:
index:
number_of_shards: 1
number_of_replicas: 1
----------------------------
--
[[remote-audit-settings]]
==== Remote Audit Log Indexing Configuration Settings
To index audit events to a remote {es} cluster, you configure the following
`xpack.security.audit.index.client` settings:
`xpack.security.audit.index.client.hosts`::
Specifies a comma-separated list of `host:port` pairs. These hosts should be
nodes in the remote cluster. If you are using default values for the
<> setting, you can omit the
`port` value. Otherwise, it must match the `transport.tcp.port` setting.
`xpack.security.audit.index.client.cluster.name`::
Specifies the name of the remote cluster.
`xpack.security.audit.index.client.xpack.security.user`::
Specifies the `username:password` pair that is used to authenticate with the
remote cluster. This user must have authority to create the `.security-audit`
index on the remote cluster.
If the remote {es} cluster has Transport Layer Security (TLS/SSL) enabled, you
must set the following setting to `true`:
`xpack.security.audit.index.client.xpack.security.transport.ssl.enabled`::
Used to enable or disable TLS/SSL for the transport client that forwards audit
logs to the remote cluster. The default is `false`.
You must also specify the information necessary to access certificates. See
<>.
You can pass additional settings to the remote client by specifying them in the
`xpack.security.audit.index.client` namespace. For example, you can add
<> and
<> in that namespace. To allow the remote
client to discover all of the nodes in the remote cluster you can specify the
`client.transport.sniff` setting:
[source,yaml]
----------------------------
xpack.security.audit.index.client.transport.sniff: true
----------------------------