183 lines
7.3 KiB
Plaintext
183 lines
7.3 KiB
Plaintext
[role="xpack"]
|
|
[[auditing-settings]]
|
|
=== Auditing Security Settings
|
|
++++
|
|
<titleabbrev>Auditing Settings</titleabbrev>
|
|
++++
|
|
|
|
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
|
|
file named `<clustername>_audit.log` on each 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.
|
|
+
|
|
For backwards compatibility reasons, if you use the logfile output type, a
|
|
`<clustername>_access.log` file is also created. It contains the same
|
|
information, but it uses the older (pre-6.5.0) formatting style.
|
|
If the backwards compatible format is not required, it should be disabled.
|
|
To do that, change its logger level to `off` in the `log4j2.properties` file.
|
|
For more information, see <<configuring-logging-levels>>.
|
|
+
|
|
--
|
|
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.emit_node_name`::
|
|
Specifies whether to include the <<node.name,node name>> as a field in
|
|
each audit event.
|
|
The default value is `true`.
|
|
|
|
`xpack.security.audit.logfile.emit_node_host_address`::
|
|
Specifies whether to include the node's IP address as a field in each audit event.
|
|
The default value is `false`.
|
|
|
|
`xpack.security.audit.logfile.emit_node_host_name`::
|
|
Specifies whether to include the node's host name as a field in each audit event.
|
|
The default value is `false`.
|
|
|
|
`xpack.security.audit.logfile.emit_node_id`::
|
|
Specifies whether to include the node id as a field in each audit event.
|
|
This is available for the new format only. That is to say, this information
|
|
does not exist in the `<clustername>_access.log` file.
|
|
Unlike <<node.name,node name>>, whose value might change if the administrator
|
|
changes the setting in the config file, the node id will persist across cluster
|
|
restarts and the administrator cannot change it.
|
|
The default value is `true`.
|
|
|
|
[[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
|
|
----------------------------
|
|
--
|
|
+
|
|
--
|
|
NOTE: These settings apply to the local audit indices, as well as to the
|
|
<<remote-audit-settings, remote audit indices>>, but only if the remote cluster
|
|
does *not* have {security} installed, or the {es} versions are different.
|
|
If the remote cluster has {security} installed, and the versions coincide, the
|
|
settings for the audit indices there will take precedence,
|
|
even if they are unspecified (i.e. left to defaults).
|
|
--
|
|
|
|
[[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
|
|
<<common-network-settings,`transport.tcp.port`>> 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
|
|
<<auditing-tls-ssl-settings>>.
|
|
|
|
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
|
|
<<modules-transport,transport settings>> and
|
|
<<tcp-settings,advanced TCP settings>> 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
|
|
----------------------------
|