honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[7.x] [DOCS] Add supported ESS settings to ES docs (#57953) (#58981) 

* Adding ESS icons to supported ES settings.

* Adding new file for supported ESS settings.

* Adding supported ESS settings for HTTP and disk-based shard allocation.

* Adding more supported settings for ESS.

* Adding descriptions for each Cloud section, plus additional settings.

* Adding new warehouse file for Cloud, plus additional settings.

* Adding node settings for Cloud.

* Adding audit settings for Cloud.

* Resolving merge conflict.

* Adding SAML settings (part 1).

* Adding SAML realm encryption and signing settings.

* Adding SAML SSL settings.

* Adding Kerberos realm settings.

* Adding OpenID Connect Realm settings.

* Adding OpenID Connect SSL settings.

* Resolving leftover Git merge markers.

* Removing Cloud settings page and link to it.

* Add link to mapping source

* Update docs/reference/docs/reindex.asciidoc

* Incorporate edit of HTTP settings

* Remove "cloud" from tag and ID

* Remove "cloud" from tag and update description

* Remove "cloud" from tag and ID

* Change "whitelists" to "specifies"

* Remove "cloud" from end tag

* Removing cloud from IDs and tags.

* Changing link reference to fix build issue.

* Adding index management page for missing settings.

* Removing warehouse file for Cloud and moving settings elsewhere.

* Clarifying true/false usage of http.detailed_errors.enabled.

* Changing underscore to dash in link to fix ci build.
This commit is contained in:
Adam Locke 2020-07-02 19:40:45 -04:00 committed by GitHub
parent 9d1bf383d0
commit 20d04081ec
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
18 changed files with 862 additions and 517 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/reference/docs/index_.asciidoc
View File

@ -180,7 +180,7 @@ automatic creation of indices that match specified patterns, or set it to
comma-separated list of patterns you want to allow, or prefix each pattern with
`+` or `-` to indicate whether it should be allowed or blocked. When a list is
specified, the default behaviour is to disallow.
+
IMPORTANT: The `action.auto_create_index` setting only affects the automatic
creation of indices. It does not affect the creation of data streams.

9
docs/reference/docs/reindex.asciidoc
View File

@ -17,6 +17,7 @@ all documents in the source.
The destination must exist and should be configured as wanted before calling `_reindex`.
Reindex does not copy the settings from the source or its associated template.
Mappings, shard counts, replicas, and so on must be configured ahead of time.
=================================================
@ -70,8 +71,11 @@ POST _reindex
[[docs-reindex-api-desc]]
==== {api-description-title}
Extracts the <<mapping-source-field,document source>> from the reindex request's source and indexes the documents into the destination.
You can copy all documents to the destination, or reindex a subset of the documents.
// tag::docs-reindex-api-desc-tag[]
Extracts the <<mapping-source-field,document source>> from the source index and indexes the documents into the destination index.
You can copy all documents to the destination index, or reindex a subset of the documents.
// end::docs-reindex-api-desc-tag[]
Just like <<docs-update-by-query,`_update_by_query`>>, `_reindex` gets a
snapshot of the source but its destination must be **different** so
@ -532,7 +536,6 @@ the special value `_doc`. See <<removal-of-types>> for further details.
`script`::
`source`:::
(Optional, string) The script to run to update the document source or metadata when reindexing.
`lang`:::
(Optional, enum) The script language: `painless`, `expression`, `mustache`, `java`.
For more information, see <<modules-scripting>>.

18
docs/reference/index-modules.asciidoc
View File

@ -12,6 +12,8 @@ an index.
[[index-modules-settings]]
== Index Settings
[[index-modules-settings-description]]
// tag::index-modules-settings-description-tag[]
Index level settings can be set per-index. Settings may be:
_static_::
@ -23,6 +25,7 @@ _dynamic_::
They can be changed on a live index using the
<<indices-update-settings,update-index-settings>> API.
// end::index-modules-settings-description-tag[]
WARNING: Changing static or dynamic index settings on a closed index could
result in incorrect settings that are impossible to rectify without deleting
@ -34,15 +37,14 @@ and recreating the index.
Below is a list of all _static_ index settings that are not associated with any
specific index module:
`index.number_of_shards`::
[[index-number-of-shards]]
// tag::index-number-of-shards-tag[]
`index.number_of_shards` {ess-icon}::
The number of primary shards that an index should have. Defaults to `1`. This setting can only be set at index creation time. It cannot be changed on a closed index.
+
NOTE: The number of shards are limited to `1024` per index. This limitation is a safety limit to prevent accidental creation of indices that can destabilize a cluster due to resource allocation. The limit can be modified by specifying `export ES_JAVA_OPTS="-Des.index.max_number_of_shards=128"` system property on every node that is part of the cluster.
The number of primary shards that an index should have. Defaults to 1.
This setting can only be set at index creation time. It cannot be
changed on a closed index. Note: the number of shards are limited to `1024` per
index. This limitation is a safety limit to prevent accidental creation of indices
that can destabilize a cluster due to resource allocation. The limit can be modified
by specifying `export ES_JAVA_OPTS="-Des.index.max_number_of_shards=128"` system property on every node that is
part of the cluster.
// end::index-number-of-shards-tag[]
`index.shard.check_on_startup`::

13
docs/reference/index-modules/blocks.asciidoc
View File

@ -22,6 +22,16 @@ index:
Set to `true` to make the index and index metadata read only, `false` to
allow writes and metadata changes.
`index.blocks.read_only_allow_delete`::
Similar to `index.blocks.read_only`, but also allows deleting the index to
make more resources available. The <<disk-based-shard-allocation,disk-based shard
allocator>> may add and remove this block automatically.
+
Deleting documents from an index to release resources - rather than deleting the index itself - can increase the index size over time. When `index.blocks.read_only_allow_delete` is set to `true`, deleting documents is not permitted. However, deleting the index itself releases the read-only index block and makes resources available almost immediately.
+
IMPORTANT: {es} adds and removes the read-only index block automatically when the disk utilization falls below the high watermark, controlled by <<cluster-routing-flood-stage,cluster.routing.allocation.disk.watermark.flood_stage>>.
`index.blocks.read`::
Set to `true` to disable read operations against the index.
@ -51,7 +61,7 @@ disk space. When you delete an index the data is removed from disk almost
immediately, freeing the space it consumes.
IMPORTANT: {es} adds the read-only-allow-delete index block automatically when
disk utilisation exceeds the <<cluster-routing-flood_stage,flood-stage
disk utilisation exceeds the <<cluster-routing-flood-stage,flood-stage
watermark>> and removes it again when disk utilisation is below the
<<cluster-routing-watermark-high,high watermark>>. You should not apply this
block yourself.
@ -148,4 +158,3 @@ The API returns following response:
} ]
}
--------------------------------------------------

59
docs/reference/modules/cluster/disk_allocator.asciidoc
View File

@ -1,6 +1,7 @@
[[disk-based-shard-allocation]]
==== Disk-based shard allocation settings
[[disk-based-shard-allocation-description]]
// tag::disk-based-shard-allocation-description-tag[]
{es} considers the available disk space on a node before deciding
whether to allocate new shards to that node or to actively relocate shards away
from that node.
@ -13,43 +14,42 @@ file or updated dynamically on a live cluster with the
Defaults to `true`. Set to `false` to disable the disk allocation decider.
[[cluster-routing-watermark-low]]
`cluster.routing.allocation.disk.watermark.low`::
[[cluster-routing-disk-threshold]]
// tag::cluster-routing-disk-threshold-tag[]
`cluster.routing.allocation.disk.threshold_enabled` {ess-icon}::
+
Defaults to `true`. Set to `false` to disable the disk allocation decider.
// end::cluster-routing-disk-threshold-tag[]
Controls the low watermark for disk usage. It defaults to `85%`, meaning
that {es} will not allocate shards to nodes that have more than
85% disk used. It can also be set to an absolute byte value (like `500mb`)
to prevent {es} from allocating shards if less than the specified
amount of space is available. This setting has no effect on the primary
shards of newly-created indices but will prevent their replicas from being allocated.
[[cluster-routing-watermark-low]]
// tag::cluster-routing-watermark-low-tag[]
`cluster.routing.allocation.disk.watermark.low` {ess-icon}::
+
Controls the low watermark for disk usage. It defaults to `85%`, meaning that {es} will not allocate shards to nodes that have more than 85% disk used. It can also be set to an absolute byte value (like `500mb`) to prevent {es} from allocating shards if less than the specified amount of space is available. This setting has no effect on the primary shards of newly-created indices but will prevent their replicas from being allocated.
// end::cluster-routing-watermark-low-tag[]
[[cluster-routing-watermark-high]]
`cluster.routing.allocation.disk.watermark.high`::
// tag::cluster-routing-watermark-high-tag[]
`cluster.routing.allocation.disk.watermark.high` {ess-icon}::
+
Controls the high watermark. It defaults to `90%`, meaning that {es} will attempt to relocate shards away from a node whose disk usage is above 90%. It can also be set to an absolute byte value (similarly to the low watermark) to relocate shards away from a node if it has less than the specified amount of free space. This setting affects the allocation of all shards, whether previously allocated or not.
// end::cluster-routing-watermark-high-tag[]
Controls the high watermark. It defaults to `90%`, meaning that
{es} will attempt to relocate shards away from a node whose disk
usage is above 90%. It can also be set to an absolute byte value (similarly
to the low watermark) to relocate shards away from a node if it has less
than the specified amount of free space. This setting affects the
allocation of all shards, whether previously allocated or not.
`cluster.routing.allocation.disk.watermark.enable_for_single_data_node`::
For a single data node, the default is to disregard disk watermarks when
making an allocation decision. This is deprecated behavior and will be
changed in 8.0. This setting can be set to `true` to enable the
disk watermarks for a single data node cluster (will become default in 8.0).
[[cluster-routing-flood_stage]]
`cluster.routing.allocation.disk.watermark.flood_stage`::
[[cluster-routing-flood-stage]]
// tag::cluster-routing-flood-stage-tag[]
`cluster.routing.allocation.disk.watermark.flood_stage` {ess-icon}::
+
--
Controls the flood stage watermark, which defaults to 95%. {es} enforces a read-only index block
(`index.blocks.read_only_allow_delete`) on every index that has one or more
shards allocated on the node, and that has at least one disk exceeding the flood
stage. This setting is a last resort to prevent nodes from running out of disk space.
The index block is automatically released when the disk utilization falls below
the high watermark.
Controls the flood stage watermark, which defaults to 95%. {es} enforces a read-only index block (`index.blocks.read_only_allow_delete`) on every index that has one or more shards allocated on the node, and that has at least one disk exceeding the flood stage. This setting is a last resort to prevent nodes from running out of disk space. The index block is automatically released when the disk utilization falls below the high watermark.
NOTE: You cannot mix the usage of percentage values and byte values within
these settings. Either all values are set to percentage values, or all are set to byte
values. This enforcement is so that {es} can validate that the settings are internally
consistent, ensuring that the low disk threshold is less than the high disk
threshold, and the high disk threshold is less than the flood stage
threshold.
these settings. Either all values are set to percentage values, or all are set to byte values. This enforcement is so that {es} can validate that the settings are internally consistent, ensuring that the low disk threshold is less than the high disk threshold, and the high disk threshold is less than the flood stage threshold.
An example of resetting the read-only index block on the `twitter` index:
@ -62,6 +62,7 @@ PUT /twitter/_settings
--------------------------------------------------
// TEST[setup:twitter]
--
// end::cluster-routing-flood-stage-tag[]
`cluster.info.update.interval`::

146
docs/reference/modules/http.asciidoc
View File

@ -1,6 +1,7 @@
[[modules-http]]
=== HTTP
[[modules-http-description]]
// tag::modules-http-description-tag[]
The HTTP layer exposes {es}'s REST APIs over HTTP.
The HTTP mechanism is completely asynchronous in nature, meaning that
@ -13,105 +14,118 @@ http://en.wikipedia.org/wiki/Keepalive#HTTP_Keepalive[HTTP keep alive]
when connecting for better performance and try to get your favorite
client not to do
http://en.wikipedia.org/wiki/Chunked_transfer_encoding[HTTP chunking].
// end::modules-http-description-tag[]
[http-settings]
==== HTTP settings
The settings in the table below can be configured for HTTP. Note that none of
them are dynamically updatable so for them to take effect they should be set in
the Elasticsearch <<settings, configuration file>>.
The following settings can be configured for HTTP. These settings also use the common <<modules-network,network settings>>.
[cols="<,<",options="header",]
|=======================================================================
|Setting |Description
|`http.port` |A bind port range. Defaults to `9200-9300`.
NOTE: HTTP settings cannot be updated dynamically. You must configure these settings in the {es} <<settings, configuration file>>
and restart {es} for changes to take effect.
|`http.publish_port` |The port that HTTP clients should use when
`http.port`::
A bind port range. Defaults to `9200-9300`.
`http.publish_port`::
The port that HTTP clients should use when
communicating with this node. Useful when a cluster node is behind a
proxy or firewall and the `http.port` is not directly addressable
from the outside. Defaults to the actual port assigned via `http.port`.
|`http.bind_host` |The host address to bind the HTTP service to. Defaults to `http.host` (if set) or `network.bind_host`.
`http.bind_host`::
The host address to bind the HTTP service to. Defaults to `http.host` (if set) or `network.bind_host`.
|`http.publish_host` |The host address to publish for HTTP clients to connect to. Defaults to `http.host` (if set) or `network.publish_host`.
`http.publish_host`::
The host address to publish for HTTP clients to connect to. Defaults to `http.host` (if set) or `network.publish_host`.
|`http.host` |Used to set the `http.bind_host` and the `http.publish_host`.
`http.host`::
Used to set the `http.bind_host` and the `http.publish_host`.
|`http.max_content_length` |The max content of an HTTP request. Defaults to
`100mb`.
`http.max_content_length`::
The max content of an HTTP request. Defaults to `100MB`.
|`http.max_initial_line_length` |The max length of an HTTP URL. Defaults
to `4kb`
`http.max_initial_line_length`::
The max length of an HTTP URL. Defaults to `4KB`.
|`http.max_header_size` | The max size of allowed headers. Defaults to `8kB`
|`http.compression` |Support for compression when possible (with
Accept-Encoding). If HTTPS is enabled, defaults to `false`. Otherwise, defaults
to `true`.
`http.max_header_size`::
The max size of allowed headers. Defaults to `8KB`.
[[http-compression]]
// tag::http-compression-tag[]
`http.compression` {ess-icon}::
Support for compression when possible (with Accept-Encoding). If HTTPS is enabled, defaults to `false`. Otherwise, defaults to `true`.
+
Disabling compression for HTTPS mitigates potential security risks, such as a
https://en.wikipedia.org/wiki/BREACH[BREACH attack]. To compress HTTPS traffic,
you must explicitly set `http.compression` to `true`.
// end::http-compression-tag[]
|`http.compression_level` |Defines the compression level to use for HTTP responses. Valid values are in the range of 1 (minimum compression)
and 9 (maximum compression). Defaults to `3`.
`http.compression_level`::
Defines the compression level to use for HTTP responses. Valid values are in the range of 1 (minimum compression) and 9 (maximum compression). Defaults to `3`.
|`http.cors.enabled` |Enable or disable cross-origin resource sharing,
i.e. whether a browser on another origin can execute requests against
Elasticsearch. Set to `true` to enable Elasticsearch to process pre-flight
[[http-cors-enabled]]
// tag::http-cors-enabled-tag[]
`http.cors.enabled` {ess-icon}::
Enable or disable cross-origin resource sharing, which determines whether a browser on another origin can execute requests against {es}. Set to `true` to enable {es} to process pre-flight
https://en.wikipedia.org/wiki/Cross-origin_resource_sharing[CORS] requests.
Elasticsearch will respond to those requests with the `Access-Control-Allow-Origin` header
if the `Origin` sent in the request is permitted by the `http.cors.allow-origin`
list. Set to `false` (the default) to make Elasticsearch ignore the `Origin`
request header, effectively disabling CORS requests because Elasticsearch will
never respond with the `Access-Control-Allow-Origin` response header. Note that
if the client does not send a pre-flight request with an `Origin` header or it
does not check the response headers from the server to validate the
{es} will respond to those requests with the `Access-Control-Allow-Origin` header if the `Origin` sent in the request is permitted by the `http.cors.allow-origin` list. Set to `false` (the default) to make {es} ignore the `Origin` request header, effectively disabling CORS requests because {es} will never respond with the `Access-Control-Allow-Origin` response header.
+
NOTE: If the client does not send a pre-flight request with an `Origin` header or it does not check the response headers from the server to validate the
`Access-Control-Allow-Origin` response header, then cross-origin security is
compromised. If CORS is not enabled on Elasticsearch, the only way for the client
to know is to send a pre-flight request and realize the required response headers
are missing.
compromised. If CORS is not enabled on {es}, the only way for the client to know is to send a pre-flight request and realize the required response headers are missing.
|`http.cors.allow-origin` |Which origins to allow. Defaults to no origins
allowed. If you prepend and append a `/` to the value, this will
be treated as a regular expression, allowing you to support HTTP and HTTPs.
for example using `/https?:\/\/localhost(:[0-9]+)?/` would return the
request header appropriately in both cases. `*` is a valid value but is
considered a *security risk* as your Elasticsearch instance is open to cross origin
requests from *anywhere*.
// end::http-cors-enabled-tag[]
|`http.cors.max-age` |Browsers send a "preflight" OPTIONS-request to
determine CORS settings. `max-age` defines how long the result should
be cached for. Defaults to `1728000` (20 days)
[[http-cors-allow-origin]]
// tag::http-cors-allow-origin-tag[]
`http.cors.allow-origin` {ess-icon}::
Which origins to allow. If you prepend and append a forward slash (`/`) to the value, this will be treated as a regular expression, allowing you to support HTTP and HTTPs. For example, using `/https?:\/\/localhost(:[0-9]+)?/` would return the request header appropriately in both cases. Defaults to no origins allowed.
+
IMPORTANT: A wildcard (`*`) is a valid value but is considered a security risk, as your {es} instance is open to cross origin requests from *anywhere*.
|`http.cors.allow-methods` |Which methods to allow. Defaults to
`OPTIONS, HEAD, GET, POST, PUT, DELETE`.
// end::http-cors-allow-origin-tag[]
|`http.cors.allow-headers` |Which headers to allow. Defaults to
`X-Requested-With, Content-Type, Content-Length`.
[[http-cors-max-age]]
// tag::http-cors-max-age-tag[]
`http.cors.max-age` {ess-icon}::
Browsers send a "preflight" OPTIONS-request to determine CORS settings. `max-age` defines how long the result should be cached for. Defaults to `1728000` (20 days).
// end::http-cors-max-age-tag[]
|`http.cors.allow-credentials` | Whether the `Access-Control-Allow-Credentials`
header should be returned. Note: This header is only returned, when the setting is
set to `true`. Defaults to `false`
[[http-cors-allow-methods]]
// tag::http-cors-allow-methods-tag[]
`http.cors.allow-methods` {ess-icon}::
Which methods to allow. Defaults to `OPTIONS, HEAD, GET, POST, PUT, DELETE`.
// end::http-cors-allow-methods-tag[]
|`http.detailed_errors.enabled` |Enables or disables the output of detailed error messages
and stack traces in response output. Note: When set to `false` and the `error_trace` request
parameter is specified, an error will be returned; when `error_trace` is not specified, a
simple message will be returned. Defaults to `true`
[[http-cors-allow-headers]]
// tag::http-cors-allow-headers-tag[]
`http.cors.allow-headers` {ess-icon}::
Which headers to allow. Defaults to `X-Requested-With, Content-Type, Content-Length`.
// end::http-cors-allow-headers-tag[]
|`http.pipelining.max_events` |The maximum number of events to be queued up in memory before an HTTP connection is closed, defaults to `10000`.
[[http-cors-allow-credentials]]
// tag::http-cors-allow-credentials-tag[]
`http.cors.allow-credentials` {ess-icon}::
Whether the `Access-Control-Allow-Credentials` header should be returned. Defaults to `false`.
+
NOTE: This header is only returned when the setting is set to `true`.
|`http.max_warning_header_count` |The maximum number of warning headers in
client HTTP responses, defaults to unbounded.
// end::http-cors-allow-credentials-tag[]
|`http.max_warning_header_size` |The maximum total size of warning headers in
client HTTP responses, defaults to unbounded.
`http.detailed_errors.enabled`::
If `true`, enables the output of detailed error messages and stack traces in the response output. Defaults to `true`.
+
If `false`, use the `error_trace` parameter to <<common-options-error-options,enable stack traces>> and return detailed error messages. Otherwise, only a simple message will be returned.
|=======================================================================
`http.pipelining.max_events`::
The maximum number of events to be queued up in memory before an HTTP connection is closed, defaults to `10000`.
It also uses the common
<<modules-network,network settings>>.
`http.max_warning_header_count`::
The maximum number of warning headers in client HTTP responses. Defaults to `unbounded`.
`http.max_warning_header_size`::
The maximum total size of warning headers in client HTTP responses. Defaults to `unbounded`.
[http-rest-request-tracer]
==== REST request tracer

44
docs/reference/modules/indices/circuit_breaker.asciidoc
View File

@ -1,13 +1,12 @@
[[circuit-breaker]]
=== Circuit breaker settings
Elasticsearch contains multiple circuit breakers used to prevent operations from
causing an OutOfMemoryError. Each breaker specifies a limit for how much memory
it can use. Additionally, there is a parent-level breaker that specifies the
total amount of memory that can be used across all breakers.
[[circuit-breaker-description]]
// tag::circuit-breaker-description-tag[]
{es} contains multiple circuit breakers used to prevent operations from causing an OutOfMemoryError. Each breaker specifies a limit for how much memory it can use. Additionally, there is a parent-level breaker that specifies the total amount of memory that can be used across all breakers.
Except where noted otherwise, these settings can be dynamically updated on a
live cluster with the <<cluster-update-settings,cluster-update-settings>> API.
// end::circuit-breaker-description-tag[]
[[parent-circuit-breaker]]
[float]
@ -21,11 +20,14 @@ The parent-level breaker can be configured with the following settings:
memory usage into account (`true`) or only consider the amount that is
reserved by child circuit breakers (`false`). Defaults to `true`.
`indices.breaker.total.limit`::
[[indices-breaker-total-limit]]
// tag::indices-breaker-total-limit-tag[]
`indices.breaker.total.limit` {ess-icon}::
Starting limit for overall parent breaker, defaults to 70% of JVM heap if
Starting limit for overall parent breaker. Defaults to 70% of JVM heap if
`indices.breaker.total.use_real_memory` is `false`. If `indices.breaker.total.use_real_memory`
is `true`, defaults to 95% of the JVM heap.
// end::indices-breaker-total-limit-tag[]
[[fielddata-circuit-breaker]]
[float]
@ -36,14 +38,20 @@ field data loading by raising an exception. By default the limit is configured
to 40% of the maximum JVM heap. It can be configured with the following
parameters:
`indices.breaker.fielddata.limit`::
[[fielddata-circuit-breaker-limit]]
// tag::fielddata-circuit-breaker-limit-tag[]
`indices.breaker.fielddata.limit` {ess-icon}::
Limit for fielddata breaker, defaults to 40% of JVM heap
Limit for fielddata breaker. Defaults to 40% of JVM heap.
// end::fielddata-circuit-breaker-limit-tag[]
`indices.breaker.fielddata.overhead`::
[[fielddata-circuit-breaker-overhead]]
// tag::fielddata-circuit-breaker-overhead-tag[]
`indices.breaker.fielddata.overhead` {ess-icon}::
A constant that all field data estimations are multiplied with to determine a
final estimation. Defaults to 1.03
final estimation. Defaults to `1.03`.
// end::fielddata-circuit-breaker-overhead-tag[]
[[request-circuit-breaker]]
[float]
@ -53,14 +61,20 @@ The request circuit breaker allows Elasticsearch to prevent per-request data
structures (for example, memory used for calculating aggregations during a
request) from exceeding a certain amount of memory.
`indices.breaker.request.limit`::
[[request-breaker-limit]]
// tag::request-breaker-limit-tag[]
`indices.breaker.request.limit` {ess-icon}::
Limit for request breaker, defaults to 60% of JVM heap
Limit for request breaker, defaults to 60% of JVM heap.
// end::request-breaker-limit-tag[]
`indices.breaker.request.overhead`::
[[request-breaker-overhead]]
// tag::request-breaker-overhead-tag[]
`indices.breaker.request.overhead` {ess-icon}::
A constant that all request estimations are multiplied with to determine a
final estimation. Defaults to 1
final estimation. Defaults to `1`.
// end::request-breaker-overhead-tag[]
[[in-flight-circuit-breaker]]
[float]

29
docs/reference/modules/indices/index_management.asciidoc Normal file
View File

@ -0,0 +1,29 @@
[[index-management-settings]]
=== Index management settings
You can configure these index settings in the `elasticsearch.yml` file.
[[auto-create-index]]
// tag::auto-create-index-tag[]
`action.auto_create_index` {ess-icon}::
<<index-creation,Automatically create an index>> if it doesn't already exist and apply any configured index templates. Default: `true`.
// end::auto-create-index-tag[]
[[action-destructive-requires-name]]
// tag::action-destructive-requires-name-tag[]
`action.destructive_requires_name` {ess-icon}::
When set to `true`, you must specify the index name to <<indices-delete-index,delete an index>>. It is not possible to delete all indices with `_all` or use wildcards.
// end::action-destructive-requires-name-tag[]
[[cluster-indices-close-enable]]
// tag::cluster-indices-close-enable-tag[]
`cluster.indices.close.enable` {ess-icon}::
Enables <<indices-open-close,opening of closed indices>> in {es}. You might enable this setting temporarily to change the analyzer configuration for an existing index. We strongly recommend leaving this set to `false` (the default) otherwise.
+
IMPORTANT: Closed indices are a data loss risk because they are not included when you make cluster configuration changes, such as scaling to a different capacity, failover, and many other operations. Additionally, closed indices can lead to inaccurate disk space counts.
[[reindex-remote-whitelist]]
// tag::reindex-remote-whitelist[]
`reindex.remote.whitelist` {ess-icon}::
Specifies the hosts that can be <<reindex-from-remote,reindexed from remotely>>. Expects a YAML array of `host:port` strings. Consists of a comma-delimited list of `host:port` entries. Defaults to `["\*.io:*", "\*.com:*"]`.
// end::reindex-remote-whitelist[]

13
docs/reference/modules/node.asciidoc
View File

@ -9,13 +9,14 @@ Every node in the cluster can handle <<modules-http,HTTP>> and
<<modules-transport,Transport>> traffic by default. The transport layer is used
exclusively for communication between nodes; the HTTP layer is used by REST
clients.
[[modules-node-description]]
// tag::modules-node-description-tag[]
All nodes know about all the other nodes in the cluster and can forward client
requests to the appropriate node.
By default, a node is all of the following types: master-eligible, data, ingest,
and (if available) machine learning and transform.
// end::modules-node-description-tag[]
TIP: As the cluster grows and in particular if you have large {ml} jobs or
{ctransforms}, consider separating dedicated master-eligible nodes from
dedicated data nodes, {ml} nodes, and {transform} nodes.
@ -30,7 +31,7 @@ A node that has the `master` role (default), which makes it eligible to be
A node that has the `data` role (default). Data nodes hold data and perform data
related operations such as CRUD, search, and aggregations.
<<ingest,Ingest node>>::
<<node-ingest-node,Ingest node>>::
A node that has the `ingest` role (default). Ingest nodes are able to apply an
<<pipeline,ingest pipeline>> to a document in order to transform and enrich the
@ -199,6 +200,12 @@ To create a dedicated ingest node, set:
node.roles: [ ingest ]
-------------------
[[node-ingest-node-setting]]
// tag::node-ingest-tag[]
`node.ingest` {ess-icon}::
Determines whether a node is an ingest node. <<ingest,Ingest nodes>> can apply an ingest pipeline to transform and enrich a document before indexing. Default: `true`.
// end::node-ingest-tag[]
[[coordinating-only-node]]
==== Coordinating only node

66
docs/reference/settings/audit-settings.asciidoc
View File

@ -4,17 +4,21 @@
++++
<titleabbrev>Auditing settings</titleabbrev>
++++
[[auditing-settings-description]]
// tag::auditing-settings-description-tag[]
You configure security auditing settings in the `elasticsearch.yml` configuration file
on each node in the cluster. For more information, see <<enable-audit-logging>>.
// end::auditing-settings-description-tag[]
[[general-audit-settings]]
==== General Auditing Settings
`xpack.security.audit.enabled`::
[[xpack-security-audit-enabled]]
// tag::xpack-security-audit-enabled-tag[]
`xpack.security.audit.enabled` {ess-icon}::
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.
// end::xpack-security-audit-enabled-tag[]
[[event-audit-settings]]
==== Audited Event Settings
@ -22,16 +26,24 @@ on each node.
The events and some other information about what gets logged can be controlled
by using the following settings:
`xpack.security.audit.logfile.events.include`::
[[xpack-sa-lf-events-include]]
// tag::xpack-sa-lf-events-include-tag[]
`xpack.security.audit.logfile.events.include` {ess-icon}::
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`.
// end::xpack-sa-lf-events-include-tag[]
`xpack.security.audit.logfile.events.exclude`::
[[xpack-sa-lf-events-exclude]]
// tag::xpack-sa-lf-events-exclude-tag[]
`xpack.security.audit.logfile.events.exclude` {ess-icon}::
Excludes the specified events from the output. By default, no events are
excluded.
// end::xpack-sa-lf-events-exclude-tag[]
`xpack.security.audit.logfile.events.emit_request_body`::
[[xpack-sa-lf-events-emit-request]]
// tag::xpack-sa-lf-events-emit-request-tag[]
`xpack.security.audit.logfile.events.emit_request_body` {ess-icon}::
Specifies whether to include the request body from REST requests on certain
event types such as `authentication_failed`. The default value is `false`.
+
@ -40,22 +52,35 @@ IMPORTANT: No filtering is performed when auditing, so sensitive data may be
audited in plain text when including the request body in audit events.
--
// end::xpack-sa-lf-events-emit-request-tag[]
[[node-audit-settings]]
==== Local Node Info Settings
`xpack.security.audit.logfile.emit_node_name`::
[[xpack-sa-lf-emit-node-name]]
// tag::xpack-sa-lf-emit-node-name-tag[]
`xpack.security.audit.logfile.emit_node_name` {ess-icon}::
Specifies whether to include the <<node.name,node name>> as a field in
each audit event. The default value is `false`.
// end::xpack-sa-lf-emit-node-name-tag[]
`xpack.security.audit.logfile.emit_node_host_address`::
[[xpack-sa-lf-emit-node-host-address]]
// tag::xpack-sa-lf-emit-node-host-address-tag[]
`xpack.security.audit.logfile.emit_node_host_address` {ess-icon}::
Specifies whether to include the node's IP address as a field in each audit event.
The default value is `false`.
// end::xpack-sa-lf-emit-node-host-address-tag[]
`xpack.security.audit.logfile.emit_node_host_name`::
[[xpack-sa-lf-emit-node-host-name]]
// tag::xpack-sa-lf-emit-node-host-name-tag[]
`xpack.security.audit.logfile.emit_node_host_name` {ess-icon}::
Specifies whether to include the node's host name as a field in each audit event.
The default value is `false`.
// end::xpack-sa-lf-emit-node-host-name-tag[]
`xpack.security.audit.logfile.emit_node_id`::
[[xpack-sa-lf-emit-node-id]]
// tag::xpack-sa-lf-emit-node-id-tag[]
`xpack.security.audit.logfile.emit_node_id` {ess-icon}::
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.
@ -63,6 +88,7 @@ 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`.
// end::xpack-sa-lf-emit-node-id-tag[]
[[audit-event-ignore-policies]]
==== Audit Logfile Event Ignore Policies
@ -73,22 +99,34 @@ All of the settings with the same policy name combine to form a single policy.
If an event matches all of the conditions for a specific policy, it is ignored
and not printed.
`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.users`::
[[xpack-sa-lf-events-ignore-users]]
// tag::xpack-sa-lf-events-ignore-users-tag[]
`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.users` {ess-icon}::
A list of user names or wildcards. The specified policy will
not print audit events for users matching these values.
// end::xpack-sa-lf-events-ignore-users-tag[]
`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.realms`::
[[xpack-sa-lf-events-ignore-realms]]
// tag::xpack-sa-lf-events-ignore-realms-tag[]
`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.realms` {ess-icon}::
A list of authentication realm names or wildcards. The specified policy will
not print audit events for users in these realms.
// end::xpack-sa-lf-events-ignore-realms-tag[]
`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.roles`::
[[xpack-sa-lf-events-ignore-roles]]
// tag::xpack-sa-lf-events-ignore-roles-tag[]
`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.roles` {ess-icon}::
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.
// end::xpack-sa-lf-events-ignore-roles-tag[]
`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.indices`::
[[xpack-sa-lf-events-ignore-indices]]
// tag::xpack-sa-lf-events-ignore-indices-tag[]
`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.indices` {ess-icon}::
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.
// end::xpack-sa-lf-events-ignore-indices-tag[]

49
docs/reference/settings/common-defs.asciidoc
View File

@ -1,16 +1,33 @@
tag::ssl-certificate[]
Specifies the path for the PEM encoded certificate (or certificate chain) that is
associated with the key.
//TBD: This setting can be used only if `ssl.key` is set.
+
This setting can be used only if `ssl.key` is set.
end::ssl-certificate[]
tag::ssl-certificate-authorities[]
List of paths to PEM encoded certificate files that should be trusted.
//TBD: You cannot use this setting and `ssl.truststore.path` at the same time.
+
This setting and `ssl.truststore.path` cannot be used at the same time.
end::ssl-certificate-authorities[]
tag::ssl-cipher-suites-values[]
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-cipher-suites-values-java11]
Supported cipher suites vary depending on which version of Java you use. For
example, for version 12 the default value is `TLS_AES_256_GCM_SHA384`,
`TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`,
`TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`,
`TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`,
`TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`, `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`,
`TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`,
`TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`,
`TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`,
`TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`,
`TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`,
`TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`,
`TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`.
+
For more information, see Oracle's
https://docs.oracle.com/en/java/javase/11/security/oracle-providers.html#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2[Java Cryptography Architecture documentation].
end::ssl-cipher-suites-values[]
tag::ssl-cipher-suites-values-java11[]
@ -44,17 +61,22 @@ end::ssl-cipher-suites-values-java11[]
tag::ssl-key-pem[]
Path to a PEM encoded file containing the private key.
//TBD: You cannot use this setting and `ssl.keystore.path` at the same time.
+
If HTTP client authentication is required, it uses this file. You cannot use
this setting and `ssl.keystore.path` at the same time.
end::ssl-key-pem[]
tag::ssl-key-passphrase[]
The passphrase that is used to decrypt the private key. Since the key might not
be encrypted, this value is optional.
//TBD: You cannot use this setting and `ssl.secure_key_passphrase` at the same time.
+
You cannot use this setting and `ssl.secure_key_passphrase` at the same time.
end::ssl-key-passphrase[]
tag::ssl-keystore-key-password[]
The password for the key in the keystore. The default is the keystore password.
+
You cannot use this setting and `ssl.keystore.secure_password` at the same time.
//TBD: You cannot use this setting and `ssl.keystore.secure_key_password` at the same time.
end::ssl-keystore-key-password[]
@ -65,6 +87,9 @@ end::ssl-keystore-password[]
tag::ssl-keystore-path[]
The path for the keystore file that contains a private key and certificate.
+
It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this
setting and `ssl.key` at the same time.
//TBD: It must be either a Java keystore (jks) or a PKCS#12 file.
//TBD: You cannot use this setting and `ssl.key` at the same time.
end::ssl-keystore-path[]
@ -106,12 +131,17 @@ end::ssl-supported-protocols[]
tag::ssl-truststore-password[]
The password for the truststore.
+
You cannot use this setting and `ssl.truststore.secure_password` at the same
time.
//TBD: You cannot use this setting and `ssl.truststore.secure_password` at the same time.
end::ssl-truststore-password[]
tag::ssl-truststore-path[]
The path for the keystore that contains the certificates to trust. It must be
either a Java keystore (jks) or a PKCS#12 file.
+
You cannot use this setting and `ssl.certificate_authorities` at the same time.
//TBD: You cannot use this setting and `ssl.certificate_authorities` at the same time.
end::ssl-truststore-path[]
@ -133,13 +163,16 @@ PKCS#12 files, use `PKCS12`. For a PKCS#11 token, use `PKCS11`. The default is
end::ssl-truststore-type-pkcs11[]
tag::ssl-verification-mode-values[]
Controls the verification of certificates.
+
Valid values are:
- `full`, which verifies that the provided certificate is signed by a trusted
* `full`, which verifies that the provided certificate is signed by a trusted
authority (CA) and also verifies that the server's hostname (or IP address)
matches the names identified within the certificate.
- `certificate`, which verifies that the provided certificate is signed by a
* `certificate`, which verifies that the provided certificate is signed by a
trusted authority (CA), but does not perform any hostname verification.
- `none`, which performs _no verification_ of the server's certificate. This
* `none`, which performs _no verification_ of the server's certificate. This
mode disables many of the security benefits of SSL/TLS and should only be used
after very careful consideration. It is primarily intended as a temporary
diagnostic mechanism when attempting to resolve TLS errors; its use on

9
docs/reference/settings/ml-settings.asciidoc
View File

@ -6,6 +6,8 @@
<titleabbrev>Machine learning settings</titleabbrev>
++++
[[ml-settings-description]]
// tag::ml-settings-description-tag[]
You do not need to configure any settings to use {ml}. It is enabled by default.
IMPORTANT: {ml-cap} uses SSE4.2 instructions, so will only work on machines whose
@ -20,6 +22,8 @@ The dynamic settings can also be updated across a cluster with the
TIP: Dynamic settings take precedence over settings in the `elasticsearch.yml`
file.
// end::ml-settings-description-tag[]
[float]
[[general-ml-settings]]
==== General machine learning settings
@ -58,13 +62,16 @@ heap on each ingest node. The cache affords faster processing times for the
or a percentage of total allocated heap. The default is "40%".
See also <<model-inference-circuit-breaker>>.
`xpack.ml.inference_model.time_to_live`::
[[xpack-interference-model-ttl]]
// tag::interference-model-ttl-tag[]
`xpack.ml.inference_model.time_to_live` {ess-icon}::
The time to live (TTL) for models in the inference model cache. The TTL is
calculated from last access. The `inference` processor attempts to load the
model from cache. If the `inference` processor does not receive any documents
for the duration of the TTL, the referenced model is flagged for eviction from
the cache. If a document is processed later, the model is again loaded into the
cache. Defaults to `5m`.
// end::interference-model-ttl-tag[]
`xpack.ml.max_inference_processors` (<<cluster-update-settings,Dynamic>>)::
The total number of `inference` type processors allowed across all ingest

14
docs/reference/settings/monitoring-settings.asciidoc
View File

@ -34,9 +34,12 @@ This deprecated setting has no effect.
[[monitoring-collection-settings]]
==== Monitoring Collection Settings
[[monitoring-settings-description]]
// tag::monitoring-settings-description-tag[]
The `xpack.monitoring.collection` settings control how data is collected from
your Elasticsearch nodes. You can dynamically change all monitoring collection
settings using the <<cluster-update-settings,cluster update settings API>>.
// end::monitoring-settings-description-tag[]
`xpack.monitoring.collection.enabled` (<<cluster-update-settings,Dynamic>>)::
@ -45,7 +48,9 @@ this setting is `false` (default), {es} monitoring data is not collected and
all monitoring data from other sources such as {kib}, Beats, and Logstash is
ignored.
`xpack.monitoring.collection.interval` (<<cluster-update-settings,Dynamic>>)::
[[xpack-monitoring-collection-interval]]
// tag::monitoring-collection-interval-tag[]
`xpack.monitoring.collection.interval` (<<cluster-update-settings,Dynamic>>) {ess-icon}::
Setting to `-1` to disable data collection is no longer supported beginning with
7.0.0. deprecated[6.3.0, Use `xpack.monitoring.collection.enabled` set to `false` instead.]
@ -53,6 +58,7 @@ Setting to `-1` to disable data collection is no longer supported beginning with
Controls how often data samples are collected. Defaults to `10s`. If you
modify the collection interval, set the `xpack.monitoring.min_interval_seconds`
option in `kibana.yml` to the same value.
// end::monitoring-collection-interval-tag[]
`xpack.monitoring.elasticsearch.collection.enabled` (<<cluster-update-settings,Dynamic>>)::
@ -92,7 +98,9 @@ collect only active recoveries. Defaults to `false`.
(<<time-units,time value>>) Timeout for collecting the recovery information. Defaults to `10s`.
`xpack.monitoring.history.duration` (<<cluster-update-settings,Dynamic>>)::
[[xpack-monitoring-history-duration]]
// tag::monitoring-history-duration-tag[]
`xpack.monitoring.history.duration` (<<cluster-update-settings,Dynamic>>) {ess-icon}::
(<<time-units,time value>>) Retention duration beyond which the indices created by a Monitoring
exporter are automatically deleted. Defaults to `7d` (7 days).
@ -105,6 +113,8 @@ IMPORTANT: This setting currently only impacts `local`-type exporters. Indices c
the `http` exporter will not be deleted automatically.
--
// end::monitoring-history-duration-tag[]
`xpack.monitoring.exporters`::
Configures where the agent stores monitoring data. By default, the agent uses a

13
docs/reference/settings/notification-settings.asciidoc
View File

@ -7,6 +7,8 @@
<titleabbrev>{watcher} settings</titleabbrev>
++++
[[notification-settings-description]]
// tag::notification-settings-description-tag[]
You configure {watcher} settings to set up {watcher} and send notifications via
<<email-notification-settings,email>>,
<<slack-notification-settings,Slack>>, and
@ -17,6 +19,7 @@ with the exception of the secure settings, which you add to the {es} keystore.
For more information about creating and updating the {es} keystore, see
<<secure-settings>>. Dynamic settings can also be updated across a cluster with the
<<cluster-update-settings,cluster update settings API>>.
// end::notification-settings-description-tag[]
[float]
[[general-notification-settings]]
@ -24,17 +27,22 @@ For more information about creating and updating the {es} keystore, see
`xpack.watcher.enabled`::
Set to `false` to disable {watcher} on the node.
`xpack.watcher.encrypt_sensitive_data`::
[[xpack-watcher-encrypt-sensitive-data]]
// tag::watcher-encrypt-sensitive-data-tag[]
`xpack.watcher.encrypt_sensitive_data` {ess-icon}::
Set to `true` to encrypt sensitive data. If this setting is enabled, you
must also specify the `xpack.watcher.encryption_key` setting. For more
information, see <<encrypting-data>>.
// end::watcher-encrypt-sensitive-data-tag[]
`xpack.watcher.encryption_key` (<<secure-settings,Secure>>)::
Specifies the path to a file that contains a key for encrypting sensitive data.
If `xpack.watcher.encrypt_sensitive_data` is set to `true`, this setting is
required. For more information, see <<encrypting-data>>.
`xpack.watcher.history.cleaner_service.enabled`::
[[xpack-watcher-history-cleaner-service]]
// tag::watcher-history-cleaner-service-tag[]
`xpack.watcher.history.cleaner_service.enabled` {ess-icon}::
added:[6.3.0,Default changed to `true`.]
deprecated:[7.0.0,Watcher history indices are now managed by the `watch-history-ilm-policy` ILM policy]
+
@ -44,6 +52,7 @@ removes previous versions of {watcher} indices (for example,
{watcher} indices is determined by the `xpack.monitoring.history.duration`
setting, which defaults to 7 days. For more information about that setting,
see <<monitoring-settings>>.
// end::watcher-history-cleaner-service-tag[]
`xpack.http.proxy.host`::
Specifies the address of the proxy server to use to connect to HTTP services.

487
docs/reference/settings/security-settings.asciidoc
View File

@ -181,8 +181,11 @@ Defaults to `ssha256`.
[float]
[[realm-settings]]
==== Realm settings
// tag::realm-settings-description-tag[]
You configure realm settings in the `xpack.security.authc.realms`
namespace in `elasticsearch.yml`. For example:
namespace in `elasticsearch.yml`.
For example:
[source,yaml]
----------------------------------------
@ -207,11 +210,12 @@ information is required.
The valid settings vary depending on the realm type. For more
information, see <<setting-up-authentication>>.
// end::realm-settings-description-tag[]
[float]
[[ref-realm-settings]]
===== Settings valid for all realms
// tag::realm-order-tag[]
`order`::
The priority of the realm within the realm chain. Realms with a lower order are
consulted first. Although not required, use of this setting is strongly
@ -224,7 +228,6 @@ realm without removing its configuration information. Defaults to `true`.
[[ref-native-settings]]
[float]
===== Native realm settings
For a native realm, the `type` must be set to `native`. In addition to the
<<ref-realm-settings,settings that are valid for all realms>>, you can specify
the following optional settings:
@ -870,18 +873,22 @@ Configuring authentication delegation for PKI realms>>.
[[ref-saml-settings]]
[float]
===== SAML realm settings
// tag::saml-description-tag[]
The `type` setting must be set to `saml`. In addition to the
<<ref-realm-settings,settings that are valid for all realms>>, you can specify
the following settings:
the following settings.
// end::saml-description-tag[]
`idp.entity_id`::
// tag::saml-idp-entity-id-tag[]
`idp.entity_id` {ess-icon}::
The Entity ID of the SAML Identity Provider. An Entity ID is a URI with a
maximum length of 1024 characters. It can be a URL (https://idp.example.com/) or
a URN (`urn:example.com:idp`) and can be found in the configuration or the SAML
metadata of the Identity Provider.
// end::saml-idp-entity-id-tag[]
`idp.metadata.path`::
// tag::saml-idp-metadata-path-tag[]
`idp.metadata.path` {ess-icon}::
The path _(recommended)_ or URL to a SAML 2.0 metadata file describing the
capabilities and configuration of the Identity Provider.
If a path is provided, then it is resolved relative to the {es} config
@ -893,88 +900,129 @@ File based resources are polled at a frequency determined by the global {es}
`resource.reload.interval.high` setting, which defaults to 5 seconds.
HTTPS resources are polled at a frequency determined by the realm's
`idp.metadata.http.refresh` setting.
// end::saml-idp-metadata-path-tag[]
`idp.metadata.http.refresh`::
// tag::saml-idp-metadata-http-refresh-tag[]
`idp.metadata.http.refresh` {ess-icon}::
Controls the frequency with which `https` metadata is checked for changes.
Defaults to `1h` (1 hour).
// end::saml-idp-metadata-http-refresh-tag[]
`idp.use_single_logout`::
// tag::saml-idp-use-single-logout-tag[]
`idp.use_single_logout` {ess-icon}::
Indicates whether to utilise the Identity Provider's Single Logout service
(if one exists in the IdP metadata file).
Defaults to `true`.
// end::saml-idp-use-single-logout-tag[]
`sp.entity_id`::
// tag::saml-sp-entity-id-tag[]
`sp.entity_id` {ess-icon}::
The Entity ID to use for this SAML Service Provider. This should be entered as a
URI. We recommend that you use the base URL of your Kibana instance. For example,
`https://kibana.example.com/`.
// end::saml-sp-entity-id-tag[]
`sp.acs`::
// tag::saml-sp-acs-tag[]
`sp.acs` {ess-icon}::
The URL of the Assertion Consumer Service within {kib}. Typically this is the
"api/security/v1/saml" endpoint of your Kibana server. For example,
`https://kibana.example.com/api/security/v1/saml`.
"api/security/saml/callback" endpoint of your Kibana server. For example,
`https://kibana.example.com/api/security/saml/callback`.
// end::saml-sp-acs-tag[]
`sp.logout`::
// tag::saml-sp-logout-tag[]
`sp.logout` {ess-icon}::
The URL of the Single Logout service within {kib}. Typically this is the
"logout" endpoint of your Kibana server. For example,
`https://kibana.example.com/logout`.
// end::saml-sp-logout-tag[]
`attributes.principal`::
// tag::saml-attributes-principal-tag[]
`attributes.principal` {ess-icon}::
The Name of the SAML attribute that contains the user's principal (username).
// end::saml-attributes-principal-tag[]
`attributes.groups`::
// tag::saml-attributes-groups-tag[]
`attributes.groups` {ess-icon}::
The Name of the SAML attribute that contains the user's groups.
// end::saml-attributes-groups-tag[]
`attributes.name`::
// tag::saml-attributes-name-tag[]
`attributes.name` {ess-icon}::
The Name of the SAML attribute that contains the user's full name.
// end::saml-attributes-name-tag[]
`attributes.mail`::
// tag::saml-attributes-mail-tag[]
`attributes.mail` {ess-icon}::
The Name of the SAML attribute that contains the user's email address.
// end::saml-attributes-mail-tag[]
`attributes.dn`::
// tag::saml-attributes-dn-tag[]
`attributes.dn` {ess-icon}::
The Name of the SAML attribute that contains the user's X.50
_Distinguished Name_.
// end::saml-attributes-dn-tag[]
`attribute_patterns.principal`::
// tag::saml-attributes-patterns-principal-tag[]
`attribute_patterns.principal` {ess-icon}::
A Java regular expression that is matched against the SAML attribute specified
by `attributes.pattern` before it is applied to the user's _principal_ property.
The attribute value must match the pattern and the value of the first
_capturing group_ is used as the principal. For example, `^([^@]+)@example\\.com$`
matches email addresses from the "example.com" domain and uses the local-part as
the principal.
// end::saml-attributes-patterns-principal-tag[]
`attribute_patterns.groups`::
// tag::saml-attributes-patterns-groups-tag[]
`attribute_patterns.groups` {ess-icon}::
As per `attribute_patterns.principal`, but for the _group_ property.
// end::saml-attributes-patterns-groups-tag[]
`attribute_patterns.name`::
// tag::saml-attributes-patterns-name-tag[]
`attribute_patterns.name` {ess-icon}::
As per `attribute_patterns.principal`, but for the _name_ property.
// end::saml-attributes-patterns-name-tag[]
`attribute_patterns.mail`::
// tag::saml-attributes-patterns-mail-tag[]
`attribute_patterns.mail` {ess-icon}::
As per `attribute_patterns.principal`, but for the _mail_ property.
// end::saml-attributes-patterns-mail-tag[]
`attribute_patterns.dn`::
// tag::saml-attributes-patterns-dn-tag[]
`attribute_patterns.dn` {ess-icon}::
As per `attribute_patterns.principal`, but for the _dn_ property.
// end::saml-attributes-patterns-dn-tag[]
`nameid_format`::
// tag::saml-nameid-format-tag[]
`nameid_format` {ess-icon}::
The NameID format that should be requested when asking the IdP to authenticate
the current user. Defaults to requesting _transient_ names
(`urn:oasis:names:tc:SAML:2.0:nameid-format:transient`).
// end::saml-nameid-format-tag[]
`nameid.allow_create`:: The value of the `AllowCreate` attribute of the
`NameIdPolicy` element in an authentication request. Defaults to `false`.
// tag::saml-nameid-allow-create-tag[]
`nameid.allow_create` {ess-icon}:: The value of the `AllowCreate` attribute of the
`NameIdPolicy` element in an authentication request. The default value is false.
// end::saml-nameid-allow-create-tag[]
`nameid.sp_qualifier`:: The value of the `SPNameQualifier` attribute of the
// tag::saml-nameid-sp-qualifier-tag[]
`nameid.sp_qualifier` {ess-icon}:: The value of the `SPNameQualifier` attribute of the
`NameIdPolicy` element in an authentication request. The default is to not
include the `SPNameQualifier` attribute.
// end::saml-nameid-sp-qualifier-tag[]
`force_authn`::
// tag::saml-force-authn-tag[]
`force_authn` {ess-icon}::
Specifies whether to set the `ForceAuthn` attribute when requesting that the IdP
authenticate the current user. If set to `true`, the IdP is required to verify
the user’s identity, irrespective of any existing sessions they might have.
Defaults to `false`.
// end::saml-force-authn-tag[]
`populate_user_metadata`::
// tag::saml-populate-user-metadata-tag[]
`populate_user_metadata` {ess-icon}::
Specifies whether to populate the {es} user's metadata with the values that are
provided by the SAML attributes. Defaults to `true`.
// end::saml-populate-user-metadata-tag[]
`authorization_realms`::
The names of the realms that should be consulted for delegated authorization.
@ -982,12 +1030,15 @@ If this setting is used, then the SAML realm does not perform role mapping and
instead loads the user from the listed realms.
See <<authorization_realms>>.
`allowed_clock_skew`::
// tag::saml-allowed-clock-skew-tag[]
`allowed_clock_skew` {ess-icon}::
The maximum amount of skew that can be tolerated between the IdP's clock and the
{es} node's clock.
Defaults to `3m` (3 minutes).
// end::saml-allowed-clock-skew-tag[]
`req_authn_context_class_ref`::
// tag::saml-req-authn-context-tag[]
`req_authn_context_class_ref` {ess-icon}::
A comma separated list of Authentication Context Class Reference values to be
included in the Requested Authentication Context when requesting the IdP to
authenticate the current user. The Authentication Context of the corresponding
@ -995,96 +1046,121 @@ authentication response should contain at least one of the requested values.
+
For more information, see
<<req-authn-context>>.
// end::saml-req-authn-context-tag[]
[float]
[[ref-saml-signing-settings]]
===== SAML realm signing settings
// tag::saml-signing-description-tag[]
If a signing key is configured (that is, either `signing.key` or
`signing.keystore.path` is set), then {es} signs outgoing SAML messages.
Signing can be configured using the following settings:
// end::saml-signing-description-tag[]
`signing.saml_messages`::
// tag::saml-signing-messages-tag[]
`signing.saml_messages` {ess-icon}::
A list of SAML message types that should be signed or `*` to sign all messages.
Each element in the list should be the local name of a SAML XML Element.
Supported element types are `AuthnRequest`, `LogoutRequest` and `LogoutResponse`.
Only valid if `signing.key` or `signing.keystore.path` is also specified.
Defaults to `*`.
// end::saml-signing-messages-tag[]
`signing.key`::
// tag::saml-signing-key-tag[]
`signing.key` {ess-icon}::
Specifies the path to the PEM encoded private key to use for SAML message signing.
`signing.key` and `signing.keystore.path` cannot be used at the same time.
// end::saml-signing-key-tag[]
`signing.secure_key_passphrase` (<<secure-settings,Secure>>)::
`signing.secure_key_passphrase` (<<secure-settings,Secure>>) {ess-icon}::
Specifies the passphrase to decrypt the PEM encoded private key (`signing.key`)
if it is encrypted.
`signing.certificate`::
// tag::saml-signing-certificate-tag[]
`signing.certificate` {ess-icon}::
Specifies the path to the PEM encoded certificate (or certificate chain) that
corresponds to the `signing.key`. This certificate must also be included in the
Service Provider metadata or manually configured within the IdP to allow for
signature validation. This setting can only be used if `signing.key` is set.
// end::saml-signing-certificate-tag[]
`signing.keystore.path`::
// tag::saml-signing-keystore-path-tag[]
`signing.keystore.path` {ess-icon}::
The path to the keystore that contains a private key and certificate. It must be
either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and
`signing.key` at the same time.
// end::saml-signing-keystore-path-tag[]
`signing.keystore.type`::
// tag::saml-signing-keystore-type-tag[]
`signing.keystore.type` {ess-icon}::
The type of the keystore in `signing.keystore.path`.
Must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx",
or "pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`.
// end::saml-signing-keystore-type-tag[]
`signing.keystore.alias`::
// tag::saml-signing-keystore-alias-tag[]
`signing.keystore.alias` {ess-icon}::
Specifies the alias of the key within the keystore that should be
used for SAML message signing. If the keystore contains more than one private
key, this setting must be specified.
// end::saml-signing-keystore-alias-tag[]
`signing.keystore.secure_password` (<<secure-settings,Secure>>)::
`signing.keystore.secure_password` (<<secure-settings,Secure>>) {ess-icon}::
The password to the keystore in `signing.keystore.path`.
`signing.keystore.secure_key_password` (<<secure-settings,Secure>>)::
`signing.keystore.secure_key_password` (<<secure-settings,Secure>>) {ess-icon}::
The password for the key in the keystore (`signing.keystore.path`).
Defaults to the keystore password.
[float]
[[ref-saml-encryption-settings]]
===== SAML realm encryption settings
// tag::saml-encryption-description-tag[]
If an encryption key is configured (that is, either `encryption.key` or
`encryption.keystore.path` is set), then {es} publishes an encryption
certificate when generating metadata and attempts to decrypt incoming SAML
content. Encryption can be configured using the following settings:
// end::saml-encryption-description-tag[]
`encryption.key`::
// tag::saml-encryption-key-tag[]
`encryption.key` {ess-icon}::
Specifies the path to the PEM encoded private key to use for SAML message
decryption.
`encryption.key` and `encryption.keystore.path` cannot be used at the same time.
// end::saml-encryption-key-tag[]
`encryption.secure_key_passphrase` (<<secure-settings,Secure>>)::
Specifies the passphrase to decrypt the PEM encoded private key
(`encryption.key`) if it is encrypted.
`encryption.certificate`::
// tag::saml-encryption-certificate-tag[]
`encryption.certificate` {ess-icon}::
Specifies the path to the PEM encoded certificate (or certificate chain) that is
associated with the `encryption.key`. This certificate must also be included in
the Service Provider metadata or manually configured within the IdP to enable
message encryption. This setting can be used only if `encryption.key` is set.
// end::saml-encryption-certificate-tag[]
`encryption.keystore.path`::
// tag::saml-encryption-keystore-path-tag[]
`encryption.keystore.path` {ess-icon}::
The path to the keystore that contains a private key and certificate. It must be
either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and
`encryption.key` at the same time.
// end::saml-encryption-keystore-path-tag[]
`encryption.keystore.type`::
// tag::saml-encryption-keystore-type-tag[]
`encryption.keystore.type` {ess-icon}::
The type of the keystore (`encryption.keystore.path`).
Must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx",
or "pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`.
// end::saml-encryption-keystore-type-tag[]
`encryption.keystore.alias`::
// tag::saml-encryption-keystore-alias-tag[]
`encryption.keystore.alias` {ess-icon}::
Specifies the alias of the key within the keystore (`encryption.keystore.path`)
that should be used for SAML message decryption. If not specified, all compatible
key pairs from the keystore are considered as candidate keys for decryption.
// end::saml-encryption-keystore-alias-tag[]
`encryption.keystore.secure_password` (<<secure-settings,Secure>>)::
The password to the keystore (`encryption.keystore.path`).
@ -1097,7 +1173,7 @@ they cannot have individual passwords.
[float]
[[ref-saml-ssl-settings]]
===== SAML realm SSL settings
// tag::saml-ssl-description-tag[]
If you are loading the IdP metadata over SSL/TLS (that is, `idp.metadata.path`
is a URL using the `https` protocol), the following settings can be used to
configure SSL.
@ -1105,45 +1181,47 @@ configure SSL.
NOTE: These settings are not used for any purpose other than loading metadata
over https.
`ssl.key`::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-pem]
+
If HTTP client authentication is required, it uses this file. You cannot use
this setting and `ssl.keystore.path` at the same time.
// end::saml-ssl-description-tag[]
`ssl.key_passphrase`::
// tag::saml-ssl-key-tag[]
`ssl.key` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-pem]
// end::saml-ssl-key-tag[]
// tag::saml-ssl-key-passphrase-tag[]
`ssl.key_passphrase` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-passphrase]
+
You cannot use this setting and `ssl.secure_key_passphrase` at the same time.
// end::saml-ssl-key-passphrase-tag[]
`ssl.secure_key_passphrase` (<<secure-settings,Secure>>)::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-secure-key-passphrase]
+
You cannot use this setting and `ssl.key_passphrase` at the same time.
`ssl.certificate`::
// tag::saml-ssl-certificate-tag[]
`ssl.certificate` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-certificate]
+
This setting can be used only if `ssl.key` is set.
// end::saml-ssl-certificate-tag[]
`ssl.certificate_authorities`::
// tag::saml-ssl-certificate-authorities-tag[]
`ssl.certificate_authorities` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-certificate-authorities]
+
This setting and `ssl.truststore.path` cannot be used at the same time.
// end::saml-ssl-certificate-authorities-tag[]
`ssl.keystore.path`::
// tag::saml-ssl-keystore-path-tag[]
`ssl.keystore.path` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-path]
+
It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this
setting and `ssl.key` at the same time.
// end::saml-ssl-keystore-path-tag[]
`ssl.keystore.type`::
// tag::saml-ssl-keystore-type[]
`ssl.keystore.type` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-type-pkcs12]
// end::saml-ssl-keystore-type[]
`ssl.keystore.password`::
// tag::saml-ssl-keystore-password-tag[]
`ssl.keystore.password` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-password]
+
You cannot use this setting and `ssl.keystore.secure_password` at the same time.
// end::saml-ssl-keystore-password-tag[]
`ssl.keystore.secure_password` (<<secure-settings,Secure>>)::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password]
@ -1160,100 +1238,129 @@ time.
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-key-password]
You cannot use this setting and `ssl.keystore.key_password` at the same time.
`ssl.truststore.path`::
// tag::saml-ssl-truststore-path-tag[]
`ssl.truststore.path` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-path]
+
You cannot use this setting and `ssl.certificate_authorities` at the same time.
// end::saml-ssl-truststore-path-tag[]
`ssl.truststore.type`::
// tag::saml-ssl-truststore-type-tag[]
`ssl.truststore.type` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-type]
// end::saml-ssl-truststore-type-tag[]
`ssl.truststore.password`::
// tag::saml-ssl-truststore-password-tag[]
`ssl.truststore.password` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-password]
+
You cannot use this setting and `ssl.truststore.secure_password` at the same
time.
// end::saml-ssl-truststore-password-tag[]
`ssl.truststore.secure_password` (<<secure-settings,Secure>>)::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password]
+
This setting cannot be used with `ssl.truststore.password`.
`ssl.verification_mode`::
Controls the verification of certificates.
// tag::saml-ssl-verification-mode-tag[]
`ssl.verification_mode` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-verification-mode-values]
// end::saml-ssl-verification-mode-tag[]
`ssl.supported_protocols`::
// tag::saml-ssl-supported-prototols-tag[]
`ssl.supported_protocols` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-supported-protocols]
// end::saml-ssl-supported-prototols-tag[]
`ssl.cipher_suites`::
// tag::saml-ssl-cipher-suites-tag[]
`ssl.cipher_suites` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-cipher-suites-values]
// end::saml-ssl-cipher-suites-tag[]
[float]
[[ref-kerberos-settings]]
===== Kerberos realm settings
// tag::kerberos-description-tag[]
For a Kerberos realm, the `type` must be set to `kerberos`. In addition to the
<<ref-realm-settings,settings that are valid for all realms>>, you can specify
the following settings:
// end::kerberos-description-tag[]
`keytab.path`:: Specifies the path to the Kerberos keytab file that contains the
// tag::kerberos-keytab-path-tag[]
`keytab.path` {ess-icon}:: Specifies the path to the Kerberos keytab file that contains the
service principal used by this {es} node. This must be a location within the
{es} configuration directory and the file must have read permissions. Required.
// end::kerberos-keytab-path-tag[]
`remove_realm_name`:: Set to `true` to remove the realm part of principal names.
// tag::kerberos-remove-realm-name-tag[]
`remove_realm_name` {ess-icon}:: Set to `true` to remove the realm part of principal names.
Principal names in Kerberos have the form `user/instance@REALM`. If this option
is `true`, the realm part (`@REALM`) will not be included in the username.
Defaults to `false`.
// end::kerberos-remove-realm-name-tag[]
`krb.debug`:: Set to `true` to enable debug logs for the Java login module that
provides support for Kerberos authentication. Defaults to `false`.
`cache.ttl`:: The time-to-live for cached user entries. A user is cached for
// tag::kerberos-cache-ttl-tag[]
`cache.ttl` {ess-icon}:: The time-to-live for cached user entries. A user is cached for
this period of time. Specify the time period using the standard {es}
<<time-units,time units>>. Defaults to `20m`.
// end::kerberos-cache-ttl-tag[]
`cache.max_users`:: The maximum number of user entries that can live in the
// tag::kerberos-cache-max-users-tag[]
`cache.max_users` {ess-icon}:: The maximum number of user entries that can live in the
cache at any given time. Defaults to 100,000.
// end::kerberos-cache-max-users-tag[]
`authorization_realms`::
// tag::kerberos-authorization-realms-tag[]
`authorization_realms` {ess-icon}::
The names of the realms that should be consulted for delegated authorization.
If this setting is used, then the Kerberos realm does not perform role mapping and
instead loads the user from the listed realms.
See <<authorization_realms>>.
// end::kerberos-authorization-realms-tag[]
[[ref-oidc-settings]]
[float]
===== OpenID Connect realm settings
// tag::oidc-description-tag[]
In addition to the <<ref-realm-settings,settings that are valid for all realms>>, you
can specify the following settings:
can specify the following settings.
// end::oidc-description-tag[]
`op.issuer`::
// tag::oidc-op-issuer-tag[]
`op.issuer` {ess-icon}::
A verifiable Identifier for your OpenID Connect Provider. An Issuer
Identifier is usually a case sensitive URL using the https scheme that contains
scheme, host, and optionally, port number and path components and no query or
fragment components. The value for this setting should be provided by your OpenID
Connect Provider.
// end::oidc-op-issuer-tag[]
`op.authorization_endpoint`::
// tag::oidc-op-auth-endpoint-tag[]
`op.authorization_endpoint` {ess-icon}::
The URL for the Authorization Endpoint at the
OpenID Connect Provider. The value for this setting should be provided by your OpenID
Connect Provider.
// end::oidc-op-auth-endpoint-tag[]
`op.token_endpoint`::
// tag::oidc-token-endpoint-tag[]
`op.token_endpoint` {ess-icon}::
The URL for the Token Endpoint at the OpenID Connect Provider.
The value for this setting should be provided by your OpenID Connect Provider.
// end::oidc-token-endpoint-tag[]
`op.userinfo_endpoint`::
// tag::oidc-userinfo-endpoint-tag[]
`op.userinfo_endpoint` {ess-icon}::
The URL for the User Info Endpoint at the OpenID Connect Provider.
The value for this setting should be provided by your OpenID Connect Provider.
// end::oidc-userinfo-endpoint-tag[]
`op.endsession_endpoint`::
// tag::oidc-endsession-endpoint-tag[]
`op.endsession_endpoint` {ess-icon}::
The URL for the End Session Endpoint at the OpenID Connect
Provider. The value for this setting should be provided by your OpenID Connect Provider.
// end::oidc-endsession-endpoint-tag[]
`op.jwkset_path`::
// tag::oidc-op-jwkset-path-tag[]
`op.jwkset_path` {ess-icon}::
The path or URL to a JSON Web Key Set with the key material that the OpenID Connect
Provider uses for signing tokens and claims responses.
If a path is provided, then it is resolved relative to the {es} config
@ -1263,85 +1370,121 @@ If a URL is provided, then it must be either a `file` URL or a `https` URL.
requests but will attempt to refresh the JWK upon signature verification
failure, as this might indicate that the OpenID Connect Provider has
rotated the signing keys.
File based resources are polled at a frequency determined by the global {es}
+
File-based resources are polled at a frequency determined by the global {es}
`resource.reload.interval.high` setting, which defaults to 5 seconds.
// end::oidc-op-jwkset-path-tag[]
`rp.client_id`::
// tag::rp-client-id-tag[]
`rp.client_id` {ess-icon}::
The OAuth 2.0 Client Identifier that was assigned to {es} during registration
at the OpenID Connect Provider
at the OpenID Connect Provider.
// end::rp-client-id-tag[]
`rp.client_secret`(<<secure-settings,Secure>>)::
The OAuth 2.0 Client Secret that was assigned to {es} during registration
at the OpenID Connect Provider
at the OpenID Connect Provider.
`rp.redirect_uri`::
// tag::rp-redirect-uri-tag[]
`rp.redirect_uri` {ess-icon}::
The Redirect URI within {kib}. If you want to use the authorization code flow, this is the
"api/security/oidc/callback" endpoint of your {kib} server. If you want to use the implicit flow, it is the "api/security/oidc/implicit" endpoint.
`api/security/oidc/callback` endpoint of your {kib} server. If you want to use the implicit flow, it is the `api/security/oidc/implicit` endpoint.
For example, `https://kibana.example.com/api/security/oidc/callback`.
// end::rp-redirect-uri-tag[]
`rp.response_type`::
// tag::rp-response-type-tag[]
`rp.response_type` {ess-icon}::
OAuth 2.0 Response Type value that determines the authorization
processing flow to be used. Can be `code` for authorization code grant flow,
or one of `id_token`, `id_token token` for the implicit flow.
// end::rp-response-type-tag[]
`rp.signature_algorithm`::
// tag::rp-signature-algorithm-tag[]
`rp.signature_algorithm` {ess-icon}::
The signature algorithm that will be used by {es} in order to verify the
signature of the id tokens it will receive from the OpenID Connect Provider.
Defaults to `RSA256`
Defaults to `RSA256`.
// end::rp-signature-algorithm-tag[]
`rp.requested_scopes`::
// tag::rp-requested-scopes-tag[]
`rp.requested_scopes` {ess-icon}::
The scope values that will be requested by the OpenID Connect Provider as
part of the Authentication Request. Optional, defaults to `openid`
// end::rp-requested-scopes-tag[]
`rp.post_logout_redirect_uri`::
// tag::rp-post-logout-redirect-url-tag[]
`rp.post_logout_redirect_uri` {ess-icon}::
The Redirect URI (usually within {kib}) that the OpenID Connect Provider
should redirect the browser to after a successful Single Logout.
// end::rp-post-logout-redirect-url-tag[]
// tag::oidc-claims-principal-tag[]
`claims.principal`::
The name of the OpenID Connect claim that contains the user's principal (username).
// end::oidc-claims-principal-tag[]
`claims.groups`::
// tag::oidc-claims-groups-tag[]
`claims.groups` {ess-icon}::
The name of the OpenID Connect claim that contains the user's groups.
// end::oidc-claims-groups-tag[]
`claims.name`::
// tag::oidc-claims-mail-tag[]
`claims.name` {ess-icon}::
The name of the OpenID Connect claim that contains the user's full name.
// end::oidc-claims-mail-tag[]
`claims.mail`::
// tag::oidc-claims-mail-tag[]
`claims.mail` {ess-icon}::
The name of the OpenID Connect claim that contains the user's email address.
// end::oidc-claims-mail-tag[]
`claims.dn`::
// tag::oidc-claims-dn-tag[]
`claims.dn` {ess-icon}::
The name of the OpenID Connect claim that contains the user's X.509
_Distinguished Name_.
// end::oidc-claims-dn-tag[]
`claim_patterns.principal`::
// tag::oidc-claim-pattern-principal-tag[]
`claim_patterns.principal` {ess-icon}::
A Java regular expression that is matched against the OpenID Connect claim specified
by `claims.principal` before it is applied to the user's _principal_ property.
The attribute value must match the pattern and the value of the first
_capturing group_ is used as the principal. For example, `^([^@]+)@example\\.com$`
matches email addresses from the "example.com" domain and uses the local-part as
the principal.
// end::oidc-claim-pattern-principal-tag[]
`claim_patterns.groups`::
// tag::oidc-claim-pattern-groups-tag[]
`claim_patterns.groups` {ess-icon}::
As per `claim_patterns.principal`, but for the _group_ property.
// end::oidc-claim-pattern-groups-tag[]
`claim_patterns.name`::
// tag::oidc-claim-pattern-name-tag[]
`claim_patterns.name` {ess-icon}::
As per `claim_patterns.principal`, but for the _name_ property.
// end::oidc-claim-pattern-name-tag[]
`claim_patterns.mail`::
// tag::oidc-claim-pattern-mail-tag[]
`claim_patterns.mail` {ess-icon}::
As per `claim_patterns.principal`, but for the _mail_ property.
// end::oidc-claim-pattern-mail-tag[]
`claim_patterns.dn`::
// tag::oidc-claim-pattern-dn-tag[]
`claim_patterns.dn` {ess-icon}::
As per `claim_patterns.principal`, but for the _dn_ property.
// end::oidc-claim-pattern-dn-tag[]
`allowed_clock_skew`::
// tag::oidc-allowed-clock-skew-tag[]
`allowed_clock_skew` {ess-icon}::
The maximum allowed clock skew to be taken into consideration when validating
id tokens with regards to their creation and expiration times.
// end::oidc-allowed-clock-skew-tag[]
`populate_user_metadata`::
// tag::oidc-populate-user-metadata-tag[]
`populate_user_metadata` {ess-icon}::
Specifies whether to populate the {es} user's metadata with the values that are
provided by the OpenID Connect claims. Defaults to `true`.
// end::oidc-populate-user-metadata-tag[]
`http.proxy.host`::
Specifies the address of the proxy server that will be used by the internal
@ -1361,83 +1504,94 @@ Specifies the port of the proxy server that will be used by the http
client for all backchannel communication to the OpenID Connect Provider
endpoints. Defaults to `80`.
`http.connect_timeout`::
// tag::oidc-http-connect-timeout-tag[]
`http.connect_timeout` {ess-icon}::
Controls the behavior of the http client used for back-channel communication to
the OpenID Connect Provider endpoints. Specifies the timeout until a connection
is established. A value of zero means the timeout is not used. Defaults to `5s`
is established. A value of zero means the timeout is not used. Defaults to `5s`.
// end::oidc-http-connect-timeout-tag[]
`http.connection_read_timeout`::
// tag::oidc-http-read-timeout-tag[]
`http.connection_read_timeout` {ess-icon}::
Controls the behavior of the http client used for back-channel communication to
the OpenID Connect Provider endpoints. Specifies the timeout used when
requesting a connection from the connection manager. Defaults to `5s`
// end::oidc-http-read-timeout-tag[]
`http.socket_timeout`::
// tag::oidc-http-socket-timeout[]
`http.socket_timeout` {ess-icon}::
Controls the behavior of the http client used for back-channel communication to
the OpenID Connect Provider endpoints. Specifies the socket timeout (SO_TIMEOUT)
in milliseconds, which is the timeout for waiting for data or, put differently,
a maximum period inactivity between two consecutive data packets). Defaults to
`5s`
`5s`.
// end::oidc-http-socket-timeout[]
`http.max_connections`::
// tag::oidc-http-max-connections-tag[]
`http.max_connections` {ess-icon}::
Controls the behavior of the http client used for back-channel communication to
the OpenID Connect Provider endpoints. Specifies the maximum number of
connections allowed across all endpoints.
// end::oidc-http-max-connections-tag[]
`http.max_endpoint_connections`::
// tag::oidc-http-max-endpoint-connections-tag[]
`http.max_endpoint_connections` {ess-icon}::
Controls the behavior of the http client used for back-channel communication to
the OpenID Connect Provider endpoints. Specifies the maximum number of
connections allowed per endpoint.
// end::oidc-http-max-endpoint-connections-tag[]
[float]
[[ref-oidc-ssl-settings]]
===== OpenID Connect realm SSL settings
// tag::oidc-ssl-description-tag[]
The following settings can be used to configure SSL for all outgoing http connections
to the OpenID Connect Provider endpoints.
NOTE: These settings are _only_ used for the back-channel communication between
{es} and the OpenID Connect Provider
`ssl.key`::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-pem]
+
If HTTP client authentication is required, it uses this file. You cannot use
this setting and `ssl.keystore.path` at the same time.
// end::oidc-ssl-description-tag[]
`ssl.key_passphrase`::
// tag::oidc-ssl-key-tag[]
`ssl.key` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-pem]
// end::oidc-ssl-key-tag[]
// tag::oidc-ssl-key-passphrase-tag[]
`ssl.key_passphrase` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-passphrase]
+
You cannot use this setting and `ssl.secure_key_passphrase` at the same
time.
// end::oidc-ssl-key-passphrase-tag[]
`ssl.secure_key_passphrase` (<<secure-settings,Secure>>)::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-secure-key-passphrase]
+
You cannot use this setting and `ssl.key_passphrase` at the same time.
`ssl.certificate`::
// tag::oidc-ssl-certificate-tag[]
`ssl.certificate` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-certificate]
+
This setting can be used only if `ssl.key` is set.
// end::oidc-ssl-certificate-tag[]
`ssl.certificate_authorities`::
// tag::oidc-ssl-certificate-authorities-tag[]
`ssl.certificate_authorities` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-certificate-authorities]
+
This setting and `ssl.truststore.path` cannot be used at the same time.
// end::oidc-ssl-certificate-authorities-tag[]
`ssl.keystore.path`::
// tag::oidc-ssl-keystore-path-tag[]
`ssl.keystore.path` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-path]
+
It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this
setting and `ssl.key` at the same time.
// end::oidc-ssl-keystore-path-tag[]
`ssl.keystore.type`::
// tag::oidc-ssl-keystore-type-tag[]
`ssl.keystore.type` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-type-pkcs12]
// end::oidc-ssl-keystore-type-tag[]
`ssl.keystore.password`::
// tag::oidc-ssl-keystore-password-tag[]
`ssl.keystore.password` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-password]
+
You cannot use this setting and `ssl.keystore.secure_password` at the same time.
// end::oidc-ssl-keystore-password-tag[]
`ssl.keystore.secure_password` (<<secure-settings,Secure>>)::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password]
@ -1455,34 +1609,41 @@ include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-key
+
You cannot use this setting and `ssl.keystore.key_password` at the same time.
`ssl.truststore.path`::
// tag::oidc-ssl-truststore-path-tag[]
`ssl.truststore.path` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-path]
+
You cannot use this setting and `ssl.certificate_authorities` at the same time.
// end::oidc-ssl-truststore-path-tag[]
`ssl.truststore.type`::
// tag::oidc-ssl-truststore-type-tag[]
`ssl.truststore.type` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-type]
// end::oidc-ssl-truststore-type-tag[]
`ssl.truststore.password`::
// tag::oidc-ssl-truststore-password-tag[]
`ssl.truststore.password` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-password]
+
You cannot use this setting and `ssl.truststore.secure_password` at the same
time.
// end::oidc-ssl-truststore-password-tag[]
`ssl.truststore.secure_password` (<<secure-settings,Secure>>)::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password]
+
You cannot use this setting and `ssl.truststore.password` at the same time.
`ssl.verification_mode`::
// tag::oidc-ssl-verification-mode-tag[]
`ssl.verification_mode` {ess-icon}::
Controls the verification of certificates.
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-verification-mode-values]
// end::oidc-ssl-verification-mode-tag[]
`ssl.supported_protocols`::
// tag::oidc-ssl-supported-protocols-tag[]
`ssl.supported_protocols` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-supported-protocols]
// end::oidc-ssl-supported-protocols-tag[]
`ssl.cipher_suites`::
// tag::oidc-ssl-cipher-suites-tag[]
`ssl.cipher_suites` {ess-icon}::
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-cipher-suites-values]
// end::oidc-ssl-cipher-suites-tag[]
[float]
[[load-balancing]]

5
docs/reference/settings/slm-settings.asciidoc
View File

@ -31,3 +31,8 @@ Defaults to daily at 1:30am UTC: `0 30 1 * * ?`.
Limits how long {slm-init} should spend deleting old snapshots.
Defaults to one hour: `1h`.
[[repositories-url-allowed]]
// tag::repositories-url-allowed[]
`repositories.url.allowed_urls` {ess-icon}::
Specifies the <<snapshots-read-only-repository,read-only URL repositories>> that snapshots can be restored from.
// end::repositories-url-allowed[]

2
docs/reference/setup.asciidoc
View File

@ -61,6 +61,8 @@ include::modules/http.asciidoc[]
include::settings/ilm-settings.asciidoc[]
include::modules/indices/index_management.asciidoc[]
include::modules/indices/recovery.asciidoc[]
include::modules/indices/indexing_buffer.asciidoc[]

5
docs/reference/snapshot-restore/register-repository.asciidoc
View File

@ -4,7 +4,8 @@
++++
<titleabbrev>Register repository</titleabbrev>
++++
[[snapshots-register-repository-description]]
// tag::snapshots-register-repository-tag[]
You must register a snapshot repository before you can perform snapshot and
restore operations. We recommend creating a new snapshot repository for each
major version. The valid repository settings depend on the repository type.
@ -12,7 +13,7 @@ major version. The valid repository settings depend on the repository type.
If you register same snapshot repository with multiple clusters, only
one cluster should have write access to the repository. All other clusters
connected to that repository should set the repository to `readonly` mode.
// end::snapshots-register-repository-tag[]
IMPORTANT: The snapshot format can change across major versions, so if you have
clusters on different versions trying to write the same repository, snapshots
written by one version may not be visible to the other and the repository could