[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.

docs/reference/docs/index_.asciidoc

@@ -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.
 

docs/reference/docs/reindex.asciidoc

@@ -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. 
+// tag::docs-reindex-api-desc-tag[]
-You can copy all documents to the destination, or reindex a subset of the documents. 
+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>>.

docs/reference/index-modules.asciidoc

@@ -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.
+// end::index-number-of-shards-tag[]
-    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.
 
 `index.shard.check_on_startup`::
 

docs/reference/index-modules/blocks.asciidoc

@@ -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:
     } ]
 }
 --------------------------------------------------
-

docs/reference/modules/cluster/disk_allocator.asciidoc

@@ -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-disk-threshold]]
-`cluster.routing.allocation.disk.watermark.low`::
+// 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
+[[cluster-routing-watermark-low]]
-    that {es} will not allocate shards to nodes that have more than
+// tag::cluster-routing-watermark-low-tag[]
-    85% disk used. It can also be set to an absolute byte value (like `500mb`)
+`cluster.routing.allocation.disk.watermark.low` {ess-icon}::
-    to prevent {es} from allocating shards if less than the specified
++
-    amount of space is available. This setting has no effect on the primary
+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.
-    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
+`cluster.routing.allocation.disk.watermark.enable_for_single_data_node`::
-    {es} will attempt to relocate shards away from a node whose disk
+    For a single data node, the default is to disregard disk watermarks when
-    usage is above 90%. It can also be set to an absolute byte value (similarly
+    making an allocation decision. This is deprecated behavior and will be
-    to the low watermark) to relocate shards away from a node if it has less
+    changed in 8.0. This setting can be set to `true` to enable the
-    than the specified amount of free space. This setting affects the
+    disk watermarks for a single data node cluster (will become default in 8.0).
-    allocation of all shards, whether previously allocated or not.
 
-[[cluster-routing-flood_stage]]
+[[cluster-routing-flood-stage]]
-`cluster.routing.allocation.disk.watermark.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
+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.
-(`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
+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.
-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`::
 

docs/reference/modules/http.asciidoc

@@ -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
+The following settings can be configured for HTTP. These settings also use the common <<modules-network,network settings>>.
-them are dynamically updatable so for them to take effect they should be set in
-the Elasticsearch <<settings, configuration file>>.
 
-[cols="<,<",options="header",]
+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.
-|Setting |Description
-|`http.port` |A bind port range. Defaults to `9200-9300`.
 
-|`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
+`http.max_content_length`::
-`100mb`.
+The max content of an HTTP request. Defaults to `100MB`.
 
-|`http.max_initial_line_length` |The max length of an HTTP URL. Defaults
+`http.max_initial_line_length`::
-to `4kb`
+The max length of an HTTP URL. Defaults to `4KB`.
 
-|`http.max_header_size` | The max size of allowed headers.  Defaults to `8kB`
+`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-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)
+`http.compression_level`::
-and 9 (maximum compression). Defaults to `3`.
+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,
+[[http-cors-enabled]]
-i.e. whether a browser on another origin can execute requests against
+// tag::http-cors-enabled-tag[]
-Elasticsearch. Set to `true` to enable Elasticsearch to process pre-flight
+`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
+{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.
-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`
+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
-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
 `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
+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.
-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
+// end::http-cors-enabled-tag[]
-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*.
 
-|`http.cors.max-age` |Browsers send a "preflight" OPTIONS-request to
+[[http-cors-allow-origin]]
-determine CORS settings. `max-age` defines how long the result should
+// tag::http-cors-allow-origin-tag[]
-be cached for. Defaults to `1728000` (20 days)
+`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
+// end::http-cors-allow-origin-tag[]
-`OPTIONS, HEAD, GET, POST, PUT, DELETE`.
 
-|`http.cors.allow-headers` |Which headers to allow. Defaults to
+[[http-cors-max-age]]
-`X-Requested-With, Content-Type, Content-Length`.
+// 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`
+[[http-cors-allow-methods]]
-header should be returned. Note: This header is only returned, when the setting is
+// tag::http-cors-allow-methods-tag[]
-set to `true`. Defaults to `false`
+`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
+[[http-cors-allow-headers]]
-and stack traces in response output. Note: When set to `false` and the `error_trace` request
+// tag::http-cors-allow-headers-tag[]
-parameter is specified, an error will be returned; when `error_trace` is not specified, a
+`http.cors.allow-headers` {ess-icon}::
-simple message will be returned. Defaults to `true`
+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
+// end::http-cors-allow-credentials-tag[]
- client HTTP responses, defaults to unbounded.
 
-|`http.max_warning_header_size` |The maximum total size of warning headers in
+`http.detailed_errors.enabled`::
-client HTTP responses, defaults to unbounded.
+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
+`http.max_warning_header_count`::
-<<modules-network,network settings>>.
+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

docs/reference/modules/indices/circuit_breaker.asciidoc

@@ -1,13 +1,12 @@
 [[circuit-breaker]]
 === Circuit breaker settings
-
+[[circuit-breaker-description]]
-Elasticsearch contains multiple circuit breakers used to prevent operations from
+// tag::circuit-breaker-description-tag[]
-causing an OutOfMemoryError. Each breaker specifies a limit for how much memory
+{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.
-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]

docs/reference/modules/indices/index_management.asciidoc

@@ -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[]

docs/reference/modules/node.asciidoc

@@ -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
 

docs/reference/settings/audit-settings.asciidoc

@@ -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[]

docs/reference/settings/common-defs.asciidoc

@@ -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

docs/reference/settings/ml-settings.asciidoc

@@ -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

docs/reference/settings/monitoring-settings.asciidoc

@@ -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

docs/reference/settings/notification-settings.asciidoc

@@ -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.

docs/reference/settings/security-settings.asciidoc

@@ -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, 
+"api/security/saml/callback" endpoint of your Kibana server. For example,
-`https://kibana.example.com/api/security/v1/saml`. 
+`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 
+// tag::saml-nameid-allow-create-tag[]
-`NameIdPolicy` element in an authentication request. Defaults to `false`. 
+`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`::
+// end::saml-ssl-description-tag[]
-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.
 
-`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]
-+
+// end::saml-ssl-key-passphrase-tag[]
-You cannot use this setting and `ssl.secure_key_passphrase` at the same time. 
 
 `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]
-+
+// end::saml-ssl-certificate-tag[]
-This setting can be used only if `ssl.key` is set.
 
-`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]
-+
+// end::saml-ssl-certificate-authorities-tag[]
-This setting and `ssl.truststore.path` cannot be used at the same time.
 
-`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]
-+
+// end::saml-ssl-keystore-path-tag[]
-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.
 
-`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]
-+
+// end::saml-ssl-keystore-password-tag[]
-You cannot use this setting and `ssl.keystore.secure_password` at the same time.
 
 `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]
-+
+// end::saml-ssl-truststore-path-tag[]
-You cannot use this setting and `ssl.certificate_authorities` at the same time.
 
-`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]
-+
+// end::saml-ssl-truststore-password-tag[]
-You cannot use this setting and `ssl.truststore.secure_password` at the same
-time.
 
 `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`::
+// tag::saml-ssl-verification-mode-tag[]
-Controls the verification of certificates.
+`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[]
 
-
+// tag::oidc-allowed-clock-skew-tag[]
-`allowed_clock_skew`::
+`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`::
+// end::oidc-ssl-description-tag[]
-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.
 
-`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]
-+
+// end::oidc-ssl-key-passphrase-tag[]
-You cannot use this setting and `ssl.secure_key_passphrase` at the same
-time.
 
 `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]
-+
+// end::oidc-ssl-certificate-tag[]
-This setting can be used only if `ssl.key` is set.
 
-`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]
-+
+// end::oidc-ssl-certificate-authorities-tag[]
-This setting and `ssl.truststore.path` cannot be used at the same time.
 
-`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]
-+
+// end::oidc-ssl-keystore-path-tag[]
-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.
 
-`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]
-+
+// end::oidc-ssl-keystore-password-tag[]
-You cannot use this setting and `ssl.keystore.secure_password` at the same time.
 
 `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]
-+
+// end::oidc-ssl-truststore-path-tag[]
-You cannot use this setting and `ssl.certificate_authorities` at the same time.
 
-`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]
-+
+// end::oidc-ssl-truststore-password-tag[]
-You cannot use this setting and `ssl.truststore.secure_password` at the same
-time.
 
 `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]]

docs/reference/settings/slm-settings.asciidoc

@@ -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[]

docs/reference/setup.asciidoc

@@ -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[]

docs/reference/snapshot-restore/register-repository.asciidoc

@@ -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