From 129b233156935409254b51e891eb80f41ff0d4e4 Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Tue, 1 Sep 2020 16:04:23 -0400 Subject: [PATCH] [DOCS] Document dynamic cluster settings (#61760) (#61817) Co-authored-by: Adam Locke --- docs/reference/modules/gateway.asciidoc | 60 +++++++++---------- .../modules/indices/query_cache.asciidoc | 13 ++-- .../modules/indices/search-settings.asciidoc | 2 +- docs/reference/modules/network.asciidoc | 21 ++++++- docs/reference/modules/transport.asciidoc | 16 +++++ .../settings/license-settings.asciidoc | 1 + docs/reference/settings/slm-settings.asciidoc | 7 ++- 7 files changed, 79 insertions(+), 41 deletions(-) diff --git a/docs/reference/modules/gateway.asciidoc b/docs/reference/modules/gateway.asciidoc index a5d5b3226bb..0558243f22c 100644 --- a/docs/reference/modules/gateway.asciidoc +++ b/docs/reference/modules/gateway.asciidoc @@ -6,52 +6,52 @@ cluster restarts. The following _static_ settings, which must be set on every master node, control how long a freshly elected master should wait before it tries to -recover the cluster state and the cluster's data: +recover the cluster state and the cluster's data. + +NOTE: These settings only take effect on a full cluster restart. `gateway.expected_nodes`:: - - deprecated:[7.7.0, This setting will be removed in 8.0. You should use `gateway.expected_data_nodes` instead.] - The number of (data or master) nodes that are expected to be in the cluster. - Recovery of local shards will start as soon as the expected number of - nodes have joined the cluster. Defaults to `0` +(<>) +deprecated:[7.7.0, This setting will be removed in 8.0. Use `gateway.expected_data_nodes` instead.] +Number of data or master nodes expected in the cluster. +Recovery of local shards begins when the expected number of +nodes join the cluster. Defaults to `0`. `gateway.expected_master_nodes`:: - - deprecated:[7.7.0, This setting will be removed in 8.0. You should use `gateway.expected_data_nodes` instead.] - The number of master nodes that are expected to be in the cluster. - Recovery of local shards will start as soon as the expected number of - master nodes have joined the cluster. Defaults to `0` +(<>) +deprecated:[7.7.0, This setting will be removed in 8.0. Use `gateway.expected_data_nodes` instead.] +Number of master nodes expected in the cluster. +Recovery of local shards begins when the expected number of +master nodes join the cluster. Defaults to `0`. `gateway.expected_data_nodes`:: - - The number of data nodes that are expected to be in the cluster. - Recovery of local shards will start as soon as the expected number of - data nodes have joined the cluster. Defaults to `0` +(<>) +Number of data nodes expected in the cluster. +Recovery of local shards begins when the expected number of +data nodes join the cluster. Defaults to `0`. `gateway.recover_after_time`:: - - If the expected number of nodes is not achieved, the recovery process waits - for the configured amount of time before trying to recover regardless. - Defaults to `5m` if one of the `expected_nodes` settings is configured. - +(<>) +If the expected number of nodes is not achieved, the recovery process waits +for the configured amount of time before trying to recover. +Defaults to `5m` if one of the `expected_nodes` settings is configured. ++ Once the `recover_after_time` duration has timed out, recovery will start as long as the following conditions are met: `gateway.recover_after_nodes`:: - - deprecated:[7.7.0, This setting will be removed in 8.0. You should use `gateway.recover_after_data_nodes` instead.] - Recover as long as this many data or master nodes have joined the cluster. +(<>) +deprecated:[7.7.0, This setting will be removed in 8.0. Use `gateway.recover_after_data_nodes` instead.] +Recover as long as this many data or master nodes have joined the cluster. `gateway.recover_after_master_nodes`:: - - deprecated:[7.7.0, This setting will be removed in 8.0. You should use `gateway.recover_after_data_nodes` instead.] - Recover as long as this many master nodes have joined the cluster. +(<>) +deprecated:[7.7.0, This setting will be removed in 8.0. Use `gateway.recover_after_data_nodes` instead.] +Recover as long as this many master nodes have joined the cluster. `gateway.recover_after_data_nodes`:: - - Recover as long as this many data nodes have joined the cluster. - -NOTE: These settings only take effect on a full cluster restart. +(<>) +Recover as long as this many data nodes have joined the cluster. [[dangling-indices]] ==== Dangling indices diff --git a/docs/reference/modules/indices/query_cache.asciidoc b/docs/reference/modules/indices/query_cache.asciidoc index 855a673eaeb..59c7e8c6ce3 100644 --- a/docs/reference/modules/indices/query_cache.asciidoc +++ b/docs/reference/modules/indices/query_cache.asciidoc @@ -22,13 +22,18 @@ The following setting is _static_ and must be configured on every data node in the cluster: `indices.queries.cache.size`:: - Controls the memory size for the filter cache , defaults to `10%`. Accepts - either a percentage value, like `5%`, or an exact value, like `512mb`. +(<>) +Controls the memory size for the filter cache. Accepts +either a percentage value, like `5%`, or an exact value, like `512mb`. Defaults to `10%`. + +[[query-cache-index-settings]] +==== Query cache index settings The following setting is an _index_ setting that can be configured on a per-index basis. Can only be set at index creation time or on a <>: `index.queries.cache.enabled`:: - Controls whether to enable query caching. Accepts `true` (default) or - `false`. +(<>) +Controls whether to enable query caching. Accepts `true` (default) or +`false`. diff --git a/docs/reference/modules/indices/search-settings.asciidoc b/docs/reference/modules/indices/search-settings.asciidoc index 7308a5b5097..3a2f83a7ede 100644 --- a/docs/reference/modules/indices/search-settings.asciidoc +++ b/docs/reference/modules/indices/search-settings.asciidoc @@ -6,7 +6,7 @@ limits. [[indices-query-bool-max-clause-count]] `indices.query.bool.max_clause_count`:: -(integer) +(<>, integer) Maximum number of clauses a Lucene BooleanQuery can contain. Defaults to `1024`. + This setting limits the number of clauses a Lucene BooleanQuery can have. The diff --git a/docs/reference/modules/network.asciidoc b/docs/reference/modules/network.asciidoc index f74ddd0b48b..795b9ddf4f2 100644 --- a/docs/reference/modules/network.asciidoc +++ b/docs/reference/modules/network.asciidoc @@ -17,6 +17,7 @@ Never expose an unprotected node to the public internet. ==== Commonly used network settings `network.host`:: +(<>) The node will bind to this hostname or IP address and _publish_ (advertise) this host to other nodes in the cluster. Accepts an IP address, hostname, a <>, or an array of any combination of @@ -29,6 +30,7 @@ same effect as the value `0.0.0.0`. Defaults to `_local_`. `discovery.seed_hosts`:: +(<>) In order to join a cluster, a node needs to know the hostname or IP address of at least some of the other nodes in the cluster. This setting provides the initial list of addresses this node will try to contact. Accepts IP addresses @@ -43,6 +45,7 @@ caching>>). Defaults to `["127.0.0.1", "[::1]"]`. `http.port`:: +(<>) Port to bind to for incoming HTTP requests. Accepts a single value or a range. If a range is specified, the node will bind to the first available port in the range. @@ -50,6 +53,7 @@ range. Defaults to `9200-9300`. `transport.port`:: +(<>) Port to bind for communication between nodes. Accepts a single value or a range. If a range is specified, the node will bind to the first available port in the range. @@ -126,39 +130,50 @@ Any component that uses TCP (like the <> and <> layers) share the following settings: `network.tcp.no_delay`:: +(<>) Enable or disable the {wikipedia}/Nagle%27s_algorithm[TCP no delay] setting. Defaults to `true`. `network.tcp.keep_alive`:: +(<>) Configures the `SO_KEEPALIVE` option for this socket, which determines whether it sends TCP keepalive probes. -`network.tcp.keep_idle`:: Configures the `TCP_KEEPIDLE` option for this socket, which +`network.tcp.keep_idle`:: +(<>) +Configures the `TCP_KEEPIDLE` option for this socket, which determines the time in seconds that a connection must be idle before starting to send TCP keepalive probes. Defaults to `-1`, which uses the system default. This value cannot exceed `300` seconds. Only applicable on Linux and macOS, and requires Java 11 or newer. -`network.tcp.keep_interval`:: Configures the `TCP_KEEPINTVL` option for this socket, +`network.tcp.keep_interval`:: +(<>) +Configures the `TCP_KEEPINTVL` option for this socket, which determines the time in seconds between sending TCP keepalive probes. Defaults to `-1`, which uses the system default. This value cannot exceed `300` seconds. Only applicable on Linux and macOS, and requires Java 11 or newer. -`network.tcp.keep_count`:: Configures the `TCP_KEEPCNT` option for this socket, which +`network.tcp.keep_count`:: +(<>) +Configures the `TCP_KEEPCNT` option for this socket, which determines the number of unacknowledged TCP keepalive probes that may be sent on a connection before it is dropped. Defaults to `-1`, which uses the system default. Only applicable on Linux and macOS, and requires Java 11 or newer. `network.tcp.reuse_address`:: +(<>) Should an address be reused or not. Defaults to `true` on non-windows machines. `network.tcp.send_buffer_size`:: +(<>) The size of the TCP send buffer (specified with <>). By default not explicitly set. `network.tcp.receive_buffer_size`:: +(<>) The size of the TCP receive buffer (specified with <>). By default not explicitly set. diff --git a/docs/reference/modules/transport.asciidoc b/docs/reference/modules/transport.asciidoc index 98fad378c34..c40ae9c34b5 100644 --- a/docs/reference/modules/transport.asciidoc +++ b/docs/reference/modules/transport.asciidoc @@ -17,9 +17,11 @@ communicates over TCP. These settings also use the common <>. `transport.port`:: +(<>) A bind port range. Defaults to `9300-9400`. `transport.publish_port`:: +(<>) The port that other nodes in the cluster should use when communicating with this node. Useful when a cluster node is behind a proxy or firewall and the `transport.port` is not directly @@ -27,25 +29,31 @@ addressable from the outside. Defaults to the actual port assigned via `transport.port`. `transport.bind_host`:: +(<>) The host address to bind the transport service to. Defaults to `transport.host` (if set) or `network.bind_host`. `transport.publish_host`:: +(<>) The host address to publish for nodes in the cluster to connect to. Defaults to `transport.host` (if set) or `network.publish_host`. `transport.host`:: +(<>) Used to set the `transport.bind_host` and the `transport.publish_host`. `transport.connect_timeout`:: +(<>) The connect timeout for initiating a new connection (in time setting format). Defaults to `30s`. `transport.compress`:: +(<>) Set to `true` to enable compression (`DEFLATE`) between all nodes. Defaults to `false`. `transport.ping_schedule`:: +(<>) Schedule a regular application-level ping message to ensure that transport connections between nodes are kept alive. Defaults to `5s` in the transport client and `-1` (disabled) elsewhere. It is preferable @@ -54,15 +62,18 @@ TCP keep-alives apply to all kinds of long-lived connections and not just to transport connections. `transport.tcp.no_delay`:: +(<>) Enable or disable the {wikipedia}/Nagle%27s_algorithm[TCP no delay] setting. Defaults to `network.tcp.no_delay`. `transport.tcp.keep_alive`:: +(<>) Configures the `SO_KEEPALIVE` option for this socket, which determines whether it sends TCP keepalive probes. Defaults to `network.tcp.keep_alive`. `transport.tcp.keep_idle`:: +(<>) Configures the `TCP_KEEPIDLE` option for this socket, which determines the time in seconds that a connection must be idle before starting to send TCP keepalive probes. Defaults to `network.tcp.keep_idle` if set, @@ -72,6 +83,7 @@ is higher than `300`, the value is automatically lowered to `300`. Only applicab Linux and macOS, and requires Java 11 or newer. `transport.tcp.keep_interval`:: +(<>) Configures the `TCP_KEEPINTVL` option for this socket, which determines the time in seconds between sending TCP keepalive probes. Defaults to `network.tcp.keep_interval` if set, or the system default otherwise. @@ -80,6 +92,7 @@ the value is automatically lowered to `300`. Only applicable on Linux and macOS, and requires Java 11 or newer. `transport.tcp.keep_count`:: +(<>) Configures the `TCP_KEEPCNT` option for this socket, which determines the number of unacknowledged TCP keepalive probes that may be sent on a connection before it is dropped. Defaults to `network.tcp.keep_count` @@ -87,13 +100,16 @@ if set, or the system default otherwise. Only applicable on Linux and macOS, and requires Java 11 or newer. `transport.tcp.reuse_address`:: +(<>) Should an address be reused or not. Defaults to `network.tcp.reuse_address`. `transport.tcp.send_buffer_size`:: +(<>) The size of the TCP send buffer (specified with <>). Defaults to `network.tcp.send_buffer_size`. `transport.tcp.receive_buffer_size`:: +(<>) The size of the TCP receive buffer (specified with <>). Defaults to `network.tcp.receive_buffer_size`. diff --git a/docs/reference/settings/license-settings.asciidoc b/docs/reference/settings/license-settings.asciidoc index 79036ff58f8..de03444768f 100644 --- a/docs/reference/settings/license-settings.asciidoc +++ b/docs/reference/settings/license-settings.asciidoc @@ -7,6 +7,7 @@ For more information, see {kibana-ref}/managing-licenses.html[License management]. `xpack.license.self_generated.type`:: +(<>) Set to `basic` (default) to enable basic {xpack} features. + + -- diff --git a/docs/reference/settings/slm-settings.asciidoc b/docs/reference/settings/slm-settings.asciidoc index 0d0c824a422..bc466f2121d 100644 --- a/docs/reference/settings/slm-settings.asciidoc +++ b/docs/reference/settings/slm-settings.asciidoc @@ -13,13 +13,13 @@ These are the settings available for configuring [[slm-history-index-enabled]] `slm.history_index_enabled`:: -(boolean) +(<>, boolean) Controls whether {slm-init} records the history of actions taken as part of {slm-init} policies to the `slm-history-*` indices. Defaults to `true`. [[slm-retention-schedule]] `slm.retention_schedule`:: -(<>, <>) +(<>, <>) Controls when the <> runs. Can be a periodic or absolute time schedule. Supports all values supported by the <>. @@ -27,12 +27,13 @@ Defaults to daily at 1:30am UTC: `0 30 1 * * ?`. [[slm-retention-duration]] `slm.retention_duration`:: -(<>, <>) +(<>, <>) 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 <> that snapshots can be restored from. // end::repositories-url-allowed[]