2018-01-18 12:18:24 -05:00
|
|
|
[role="xpack"]
|
|
|
|
[[auditing-settings]]
|
2019-03-14 17:22:06 -04:00
|
|
|
=== Auditing security settings
|
2018-01-18 12:18:24 -05:00
|
|
|
++++
|
2019-03-14 17:22:06 -04:00
|
|
|
<titleabbrev>Auditing settings</titleabbrev>
|
2018-01-18 12:18:24 -05:00
|
|
|
++++
|
2020-09-15 17:34:24 -04:00
|
|
|
|
2020-07-02 19:40:45 -04:00
|
|
|
[[auditing-settings-description]]
|
2020-09-15 17:34:24 -04:00
|
|
|
You can use <<enable-audit-logging,audit logging>> to record security-related
|
|
|
|
events, such as authentication failures, refused connections, and data-access
|
|
|
|
events.
|
|
|
|
|
|
|
|
If configured, auditing settings must be set on every node in the cluster.
|
|
|
|
Static settings, such as `xpack.security.audit.enabled`, must be configured in
|
|
|
|
`elasticsearch.yml` on each node. For dynamic auditing settings, use the
|
|
|
|
<<cluster-update-settings,cluster update settings API>> to ensure the setting is
|
|
|
|
the same on all nodes.
|
2018-01-18 12:18:24 -05:00
|
|
|
|
|
|
|
[[general-audit-settings]]
|
|
|
|
==== General Auditing Settings
|
2020-07-02 19:40:45 -04:00
|
|
|
[[xpack-security-audit-enabled]]
|
|
|
|
// tag::xpack-security-audit-enabled-tag[]
|
2020-07-06 11:20:53 -04:00
|
|
|
`xpack.security.audit.enabled`::
|
2020-09-15 17:34:24 -04:00
|
|
|
(<<static-cluster-setting,Static>>)
|
|
|
|
Set to `true` to enable auditing on the node. The default value is `false`. This
|
|
|
|
puts the auditing events in a dedicated file named `<clustername>_audit.json` on
|
|
|
|
each node.
|
|
|
|
+
|
|
|
|
If enabled, this setting must be configured in `elasticsearch.yml` on all nodes
|
|
|
|
in the cluster.
|
2020-07-02 19:40:45 -04:00
|
|
|
// end::xpack-security-audit-enabled-tag[]
|
2018-01-18 12:18:24 -05:00
|
|
|
|
|
|
|
[[event-audit-settings]]
|
|
|
|
==== Audited Event Settings
|
|
|
|
|
2019-01-24 05:36:10 -05:00
|
|
|
The events and some other information about what gets logged can be controlled
|
|
|
|
by using the following settings:
|
2018-01-18 12:18:24 -05:00
|
|
|
|
2020-07-02 19:40:45 -04:00
|
|
|
[[xpack-sa-lf-events-include]]
|
|
|
|
// tag::xpack-sa-lf-events-include-tag[]
|
2020-09-15 17:34:24 -04:00
|
|
|
`xpack.security.audit.logfile.events.include`::
|
|
|
|
(<<dynamic-cluster-setting,Dynamic>>)
|
2018-01-18 12:18:24 -05:00
|
|
|
Specifies which events to include in the auditing output. The default value is:
|
2019-01-24 05:36:10 -05:00
|
|
|
`access_denied, access_granted, anonymous_access_denied, authentication_failed,
|
|
|
|
connection_denied, tampered_request, run_as_denied, run_as_granted`.
|
2020-07-02 19:40:45 -04:00
|
|
|
// end::xpack-sa-lf-events-include-tag[]
|
2018-01-18 12:18:24 -05:00
|
|
|
|
2020-07-02 19:40:45 -04:00
|
|
|
[[xpack-sa-lf-events-exclude]]
|
|
|
|
// tag::xpack-sa-lf-events-exclude-tag[]
|
2020-09-15 17:34:24 -04:00
|
|
|
`xpack.security.audit.logfile.events.exclude`::
|
|
|
|
(<<dynamic-cluster-setting,Dynamic>>)
|
2018-01-18 12:18:24 -05:00
|
|
|
Excludes the specified events from the output. By default, no events are
|
|
|
|
excluded.
|
2020-07-02 19:40:45 -04:00
|
|
|
// end::xpack-sa-lf-events-exclude-tag[]
|
2018-01-18 12:18:24 -05:00
|
|
|
|
2020-07-02 19:40:45 -04:00
|
|
|
[[xpack-sa-lf-events-emit-request]]
|
|
|
|
// tag::xpack-sa-lf-events-emit-request-tag[]
|
2020-09-15 17:34:24 -04:00
|
|
|
`xpack.security.audit.logfile.events.emit_request_body`::
|
|
|
|
(<<dynamic-cluster-setting,Dynamic>>)
|
2018-01-18 12:18:24 -05:00
|
|
|
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.
|
|
|
|
--
|
|
|
|
|
2020-07-02 19:40:45 -04:00
|
|
|
// end::xpack-sa-lf-events-emit-request-tag[]
|
|
|
|
|
2018-01-18 12:18:24 -05:00
|
|
|
[[node-audit-settings]]
|
|
|
|
==== Local Node Info Settings
|
|
|
|
|
2020-07-02 19:40:45 -04:00
|
|
|
[[xpack-sa-lf-emit-node-name]]
|
|
|
|
// tag::xpack-sa-lf-emit-node-name-tag[]
|
2020-09-15 17:34:24 -04:00
|
|
|
`xpack.security.audit.logfile.emit_node_name`::
|
|
|
|
(<<dynamic-cluster-setting,Dynamic>>)
|
2018-10-26 08:19:35 -04:00
|
|
|
Specifies whether to include the <<node.name,node name>> as a field in
|
2020-05-20 09:34:00 -04:00
|
|
|
each audit event. The default value is `false`.
|
2020-07-02 19:40:45 -04:00
|
|
|
// end::xpack-sa-lf-emit-node-name-tag[]
|
2018-10-26 08:19:35 -04:00
|
|
|
|
2020-07-02 19:40:45 -04:00
|
|
|
[[xpack-sa-lf-emit-node-host-address]]
|
|
|
|
// tag::xpack-sa-lf-emit-node-host-address-tag[]
|
2020-09-15 17:34:24 -04:00
|
|
|
`xpack.security.audit.logfile.emit_node_host_address`::
|
|
|
|
(<<dynamic-cluster-setting,Dynamic>>)
|
2018-10-26 08:19:35 -04:00
|
|
|
Specifies whether to include the node's IP address as a field in each audit event.
|
|
|
|
The default value is `false`.
|
2020-07-02 19:40:45 -04:00
|
|
|
// end::xpack-sa-lf-emit-node-host-address-tag[]
|
2018-10-26 08:19:35 -04:00
|
|
|
|
2020-07-02 19:40:45 -04:00
|
|
|
[[xpack-sa-lf-emit-node-host-name]]
|
|
|
|
// tag::xpack-sa-lf-emit-node-host-name-tag[]
|
2020-09-15 17:34:24 -04:00
|
|
|
`xpack.security.audit.logfile.emit_node_host_name`::
|
|
|
|
(<<dynamic-cluster-setting,Dynamic>>)
|
2018-10-26 08:19:35 -04:00
|
|
|
Specifies whether to include the node's host name as a field in each audit event.
|
|
|
|
The default value is `false`.
|
2020-07-02 19:40:45 -04:00
|
|
|
// end::xpack-sa-lf-emit-node-host-name-tag[]
|
2018-10-26 08:19:35 -04:00
|
|
|
|
2020-07-02 19:40:45 -04:00
|
|
|
[[xpack-sa-lf-emit-node-id]]
|
|
|
|
// tag::xpack-sa-lf-emit-node-id-tag[]
|
2020-09-15 17:34:24 -04:00
|
|
|
`xpack.security.audit.logfile.emit_node_id`::
|
|
|
|
(<<dynamic-cluster-setting,Dynamic>>)
|
2018-10-26 08:19:35 -04:00
|
|
|
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`.
|
2020-07-02 19:40:45 -04:00
|
|
|
// end::xpack-sa-lf-emit-node-id-tag[]
|
2018-01-18 12:18:24 -05:00
|
|
|
|
2018-11-09 09:58:10 -05:00
|
|
|
[[audit-event-ignore-policies]]
|
|
|
|
==== Audit Logfile Event Ignore Policies
|
|
|
|
|
2019-10-07 18:23:19 -04:00
|
|
|
These settings affect the <<audit-log-ignore-policy,ignore policies>>
|
2018-11-09 09:58:10 -05:00
|
|
|
that enable fine-grained control over which audit events are printed to the log file.
|
|
|
|
All of the settings with the same policy name combine to form a single policy.
|
2020-07-02 19:40:45 -04:00
|
|
|
If an event matches all of the conditions for a specific policy, it is ignored
|
2018-11-09 09:58:10 -05:00
|
|
|
and not printed.
|
|
|
|
|
2020-07-02 19:40:45 -04:00
|
|
|
[[xpack-sa-lf-events-ignore-users]]
|
|
|
|
// tag::xpack-sa-lf-events-ignore-users-tag[]
|
2020-09-15 17:34:24 -04:00
|
|
|
`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.users`::
|
|
|
|
(<<dynamic-cluster-setting,Dynamic>>)
|
2018-11-09 09:58:10 -05:00
|
|
|
A list of user names or wildcards. The specified policy will
|
|
|
|
not print audit events for users matching these values.
|
2020-07-02 19:40:45 -04:00
|
|
|
// end::xpack-sa-lf-events-ignore-users-tag[]
|
2018-11-09 09:58:10 -05:00
|
|
|
|
2020-07-02 19:40:45 -04:00
|
|
|
[[xpack-sa-lf-events-ignore-realms]]
|
|
|
|
// tag::xpack-sa-lf-events-ignore-realms-tag[]
|
2020-09-15 17:34:24 -04:00
|
|
|
`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.realms`::
|
|
|
|
(<<dynamic-cluster-setting,Dynamic>>)
|
2018-11-09 09:58:10 -05:00
|
|
|
A list of authentication realm names or wildcards. The specified policy will
|
|
|
|
not print audit events for users in these realms.
|
2020-07-02 19:40:45 -04:00
|
|
|
// end::xpack-sa-lf-events-ignore-realms-tag[]
|
2018-11-09 09:58:10 -05:00
|
|
|
|
2020-07-02 19:40:45 -04:00
|
|
|
[[xpack-sa-lf-events-ignore-roles]]
|
|
|
|
// tag::xpack-sa-lf-events-ignore-roles-tag[]
|
2020-09-15 17:34:24 -04:00
|
|
|
`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.roles`::
|
|
|
|
(<<dynamic-cluster-setting,Dynamic>>)
|
2018-11-09 09:58:10 -05:00
|
|
|
A list of role names or wildcards. The specified policy will
|
|
|
|
not print audit events for users that have these roles. If the user has several
|
|
|
|
roles, some of which are *not* covered by the policy, the policy will
|
|
|
|
*not* cover this event.
|
2020-07-02 19:40:45 -04:00
|
|
|
// end::xpack-sa-lf-events-ignore-roles-tag[]
|
2018-11-09 09:58:10 -05:00
|
|
|
|
2020-07-02 19:40:45 -04:00
|
|
|
[[xpack-sa-lf-events-ignore-indices]]
|
|
|
|
// tag::xpack-sa-lf-events-ignore-indices-tag[]
|
2020-09-15 17:34:24 -04:00
|
|
|
`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.indices`::
|
|
|
|
(<<dynamic-cluster-setting,Dynamic>>)
|
2018-11-09 09:58:10 -05:00
|
|
|
A list of index names or wildcards. The specified policy will
|
|
|
|
not print audit events when all the indices in the event match
|
|
|
|
these values. If the event concerns several indices, some of which are
|
|
|
|
*not* covered by the policy, the policy will *not* cover this event.
|
2020-07-02 19:40:45 -04:00
|
|
|
// end::xpack-sa-lf-events-ignore-indices-tag[]
|