[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 ---------------------------- -- + -- NOTE: These settings apply to the local audit indices, as well as to the <>, 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 <> 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 ----------------------------