From d5ea39b2e870db16a6cc8e680d3148e1837236ab Mon Sep 17 00:00:00 2001 From: David Turner Date: Mon, 1 Aug 2022 19:59:50 +0100 Subject: [PATCH] Clean up network setting docs (#88929) Clean up network setting docs - Add types for all params - Remove mention of JDKs before 11 - Clarify some wording Co-authored-by: Stef Nestor --- docs/reference/modules/http.asciidoc | 128 ++++++++++++---------- docs/reference/modules/network.asciidoc | 78 ++++++------- docs/reference/modules/transport.asciidoc | 103 +++++++++-------- 3 files changed, 158 insertions(+), 151 deletions(-) diff --git a/docs/reference/modules/http.asciidoc b/docs/reference/modules/http.asciidoc index 9c4925fb1298d..67818f91f20c8 100644 --- a/docs/reference/modules/http.asciidoc +++ b/docs/reference/modules/http.asciidoc @@ -6,7 +6,7 @@ independently of the <>. You can also configure both interfaces together using the <>. `http.host`:: -(<>) +(<>, string) Sets the address of this node for HTTP traffic. The node will bind to this address and will also use it as its HTTP publish address. Accepts an IP address, a hostname, or a <>. @@ -16,7 +16,7 @@ transport and HTTP interfaces. Defaults to the address given by `network.host`. `http.bind_host`:: -(<>) +(<>, string) The network address(es) to which the node should bind in order to listen for incoming HTTP connections. Accepts a list of IP addresses, hostnames, and <>. Defaults to the address given by @@ -26,7 +26,7 @@ binding, and you also require different binding configurations for the transport and HTTP interfaces. `http.publish_host`:: -(<>) +(<>, string) The network address for HTTP clients to contact the node using sniffing. Accepts an IP address, a hostname, or a <>. Defaults to the address given by `http.host` or @@ -36,27 +36,27 @@ and you also require different binding configurations for the transport and HTTP interfaces. `http.publish_port`:: -(<>) +(<>, integer) The port of the <>. Configure this setting only if you need the publish port to be different from `http.port`. Defaults to the port assigned via `http.port`. `http.max_content_length`:: -(<>) +(<>, <>) Maximum size of an HTTP request body. Defaults to `100mb`. `http.max_initial_line_length`:: -(<>) +(<>, <>) Maximum size of an HTTP URL. Defaults to `4kb`. `http.max_header_size`:: -(<>) +(<>, <>) Maximum size of allowed headers. Defaults to `16kb`. [[http-compression]] // tag::http-compression-tag[] `http.compression` {ess-icon}:: -(<>) +(<>, boolean) 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 @@ -65,13 +65,13 @@ you must explicitly set `http.compression` to `true`. // end::http-compression-tag[] `http.compression_level`:: -(<>) +(<>, integer) 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]] // tag::http-cors-enabled-tag[] `http.cors.enabled` {ess-icon}:: -(<>) +(<>, boolean) 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 {wikipedia}/Cross-origin_resource_sharing[CORS] requests. {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. @@ -85,7 +85,7 @@ compromised. If CORS is not enabled on {es}, the only way for the client to know [[http-cors-allow-origin]] // tag::http-cors-allow-origin-tag[] `http.cors.allow-origin` {ess-icon}:: -(<>) +(<>, string) 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*. @@ -95,28 +95,30 @@ IMPORTANT: A wildcard (`*`) is a valid value but is considered a security risk, [[http-cors-max-age]] // tag::http-cors-max-age-tag[] `http.cors.max-age` {ess-icon}:: -(<>) -Browsers send a "preflight" OPTIONS-request to determine CORS settings. `max-age` defines how long the result should be cached for. Defaults to `1728000` (20 days). +(<>, integer) +Browsers send a "preflight" OPTIONS-request to determine CORS settings. +`max-age` defines for how long, in seconds, the result should be cached. +Defaults to `1728000` (20 days). // end::http-cors-max-age-tag[] [[http-cors-allow-methods]] // tag::http-cors-allow-methods-tag[] `http.cors.allow-methods` {ess-icon}:: -(<>) +(<>, string) Which methods to allow. Defaults to `OPTIONS, HEAD, GET, POST, PUT, DELETE`. // end::http-cors-allow-methods-tag[] [[http-cors-allow-headers]] // tag::http-cors-allow-headers-tag[] `http.cors.allow-headers` {ess-icon}:: -(<>) +(<>, string) Which headers to allow. Defaults to `X-Requested-With, Content-Type, Content-Length`. // end::http-cors-allow-headers-tag[] [[http-cors-allow-credentials]] // tag::http-cors-allow-credentials-tag[] `http.cors.allow-credentials` {ess-icon}:: -(<>) +(<>, boolean) 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`. @@ -124,80 +126,86 @@ NOTE: This header is only returned when the setting is set to `true`. // end::http-cors-allow-credentials-tag[] `http.detailed_errors.enabled`:: -(<>) -If `true`, enables the output of detailed error messages and stack traces in the response output. Defaults to `true`. -+ -If `false`, use the `error_trace` parameter to <> and return detailed error messages. Otherwise, only a simple message will be returned. +(<>, boolean) +Configures whether detailed error reporting in HTTP responses is enabled. +Defaults to `true`, which means that HTTP requests that include the +<> will return a +detailed error message including a stack trace if they encounter an exception. +If set to `false`, requests with the `?error_trace` parameter are rejected. `http.pipelining.max_events`:: -(<>) +(<>, integer) The maximum number of events to be queued up in memory before an HTTP connection is closed, defaults to `10000`. `http.max_warning_header_count`:: -(<>) -The maximum number of warning headers in client HTTP responses. Defaults to `unbounded`. +(<>, integer) +The maximum number of warning headers in client HTTP responses. Defaults to +`-1` which means the number of warning headers is unlimited. `http.max_warning_header_size`:: -(<>) -The maximum total size of warning headers in client HTTP responses. Defaults to `unbounded`. - -`http.tcp.no_delay`:: -(<>) -Enable or disable the {wikipedia}/Nagle%27s_algorithm[TCP no delay] -setting. Defaults to `network.tcp.no_delay`. +(<>, <>) +The maximum total size of warning headers in client HTTP responses. Defaults to +`-1` which means the size of the warning headers is unlimited. `http.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`. +(<>, boolean) +Configures the `SO_KEEPALIVE` option for this socket, which determines whether +it sends TCP keepalive probes. Defaults to `network.tcp.keep_alive`. `http.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`, which -uses the system default. This value cannot exceed `300` seconds. Only applicable on -Linux and macOS, and requires Java 11 or newer. +(<>, integer) +Configures the `TCP_KEEPIDLE` option for HTTP sockets, 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`, which uses the system +default. This value cannot exceed `300` seconds. Only applicable on Linux and +macOS. `http.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`, which uses the system default. -This value cannot exceed `300` seconds. Only applicable on Linux and macOS, and requires -Java 11 or newer. +(<>, integer) +Configures the `TCP_KEEPINTVL` option for HTTP sockets, which determines the +time in seconds between sending TCP keepalive probes. Defaults to +`network.tcp.keep_interval`, which uses the system default. This value cannot +exceed `300` seconds. Only applicable on Linux and macOS. `http.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`, -which uses the system default. Only applicable on Linux and macOS, and -requires Java 11 or newer. +(<>, integer) +Configures the `TCP_KEEPCNT` option for HTTP sockets, 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`, which uses the +system default. Only applicable on Linux and macOS. + +`http.tcp.no_delay`:: +(<>, boolean) +Configures the `TCP_NODELAY` option on HTTP sockets, which determines whether +{wikipedia}/Nagle%27s_algorithm[TCP no delay] is enabled. Defaults to `true`. `http.tcp.reuse_address`:: -(<>) -Should an address be reused or not. Defaults to `network.tcp.reuse_address`. +(<>, boolean) +Configures the `SO_REUSEADDR` option for HTTP sockets, which determines whether +the address can be reused or not. Defaults to `false` on Windows and `true` +otherwise. `http.tcp.send_buffer_size`:: -(<>) -The size of the TCP send buffer (specified with <>). -Defaults to `network.tcp.send_buffer_size`. +(<>, <>) +The size of the TCP send buffer for HTTP traffic. Defaults to +`network.tcp.send_buffer_size`. `http.tcp.receive_buffer_size`:: -(<>) -The size of the TCP receive buffer (specified with <>). -Defaults to `network.tcp.receive_buffer_size`. +(<>, <>) +The size of the TCP receive buffer for HTTP traffic. Defaults to +`network.tcp.receive_buffer_size`. `http.client_stats.enabled`:: -(<>) +(<>, boolean) Enable or disable collection of HTTP client stats. Defaults to `true`. `http.client_stats.closed_channels.max_count`:: -(<>) +(<>, integer) When `http.client_stats.enabled` is `true`, sets the maximum number of closed HTTP channels for which {es} reports statistics. Defaults to `10000`. `http.client_stats.closed_channels.max_age`:: -(<>) +(<>, <>) When `http.client_stats.enabled` is `true`, sets the maximum length of time after closing a HTTP channel that {es} will report that channel's statistics. Defaults to `5m`. diff --git a/docs/reference/modules/network.asciidoc b/docs/reference/modules/network.asciidoc index e1d6500e7749d..240decbcca4d9 100644 --- a/docs/reference/modules/network.asciidoc +++ b/docs/reference/modules/network.asciidoc @@ -38,7 +38,7 @@ proceeding. Most users will need to configure only the following network settings. `network.host`:: -(<>) +(<>, string) Sets the address of this node for both HTTP and transport traffic. The node will bind to this address and will also use it as its publish address. Accepts an IP address, a hostname, or a <>. @@ -46,7 +46,7 @@ an IP address, a hostname, or a <>. Defaults to `_local_`. `http.port`:: -(<>) +(<>, integer) The port to bind for HTTP client communication. Accepts a single value or a range. If a range is specified, the node will bind to the first available port in the range. @@ -54,7 +54,7 @@ in the range. Defaults to `9200-9300`. `transport.port`:: -(<>) +(<>, integer) The 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. Set this setting to a single port, not a range, on every @@ -170,7 +170,7 @@ you should not use them if you can use the <> instead. `network.bind_host`:: -(<>) +(<>, string) The network address(es) to which the node should bind in order to listen for incoming connections. Accepts a list of IP addresses, hostnames, and <>. Defaults to the address given by @@ -178,7 +178,7 @@ incoming connections. Accepts a list of IP addresses, hostnames, and different addresses for publishing and binding. `network.publish_host`:: -(<>) +(<>, string) The network address that clients and other nodes can use to contact this node. Accepts an IP address, a hostname, or a <>. Defaults to the address given by `network.host`. Use this setting only @@ -199,53 +199,53 @@ each node is accessible at all possible publish addresses. Use the following settings to control the low-level parameters of the TCP connections used by the HTTP and transport interfaces. -`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. +(<>, boolean) +Configures the `SO_KEEPALIVE` option for network sockets, which determines +whether each connection sends TCP keepalive probes. Defaults to `true`. `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. +(<>, integer) +Configures the `TCP_KEEPIDLE` option for network sockets, which determines the +time in seconds that a connection must be idle before starting to send TCP +keepalive probes. Defaults to `-1`, which means to use the system default. This +value cannot exceed `300` seconds. Only applicable on Linux and macOS. `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. +(<>, integer) +Configures the `TCP_KEEPINTVL` option for network sockets, which determines the +time in seconds between sending TCP keepalive probes. Defaults to `-1`, which +means to use the system default. This value cannot exceed `300` seconds. Only +applicable on Linux and macOS. `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. +(<>, integer) +Configures the `TCP_KEEPCNT` option for network sockets, which determines the +number of unacknowledged TCP keepalive probes that may be sent on a connection +before it is dropped. Defaults to `-1`, which means to use the system default. +Only applicable on Linux and macOS. + +`network.tcp.no_delay`:: +(<>, boolean) +Configures the `TCP_NODELAY` option on network sockets, which determines +whether {wikipedia}/Nagle%27s_algorithm[TCP no delay] is enabled. Defaults to +`true`. `network.tcp.reuse_address`:: -(<>) -Should an address be reused or not. Defaults to `true` on non-windows -machines. +(<>, boolean) +Configures the `SO_REUSEADDR` option for network sockets, which determines +whether the address can be reused or not. Defaults to `false` on Windows and +`true` otherwise. `network.tcp.send_buffer_size`:: -(<>) -The size of the TCP send buffer (specified with <>). -By default not explicitly set. +(<>, <>) +Configures the size of the TCP send buffer for network sockets. Defaults to +`-1` which means to use the system default. `network.tcp.receive_buffer_size`:: -(<>) -The size of the TCP receive buffer (specified with <>). -By default not explicitly set. +(<>, <>) +Configures the size of the TCP receive buffer. Defaults to `-1` which means to +use the system default. include::http.asciidoc[] diff --git a/docs/reference/modules/transport.asciidoc b/docs/reference/modules/transport.asciidoc index d97c2d432fa92..3663422a36305 100644 --- a/docs/reference/modules/transport.asciidoc +++ b/docs/reference/modules/transport.asciidoc @@ -7,7 +7,7 @@ independently of the <>. Use the settings>> to configure both interfaces together. `transport.host`:: -(<>) +(<>, string) Sets the address of this node for transport traffic. The node will bind to this address and will also use it as its transport publish address. Accepts an IP address, a hostname, or a <>. @@ -17,7 +17,7 @@ transport and HTTP interfaces. Defaults to the address given by `network.host`. `transport.bind_host`:: -(<>) +(<>, string) The network address(es) to which the node should bind in order to listen for incoming transport connections. Accepts a list of IP addresses, hostnames, and <>. Defaults to the address given by @@ -27,7 +27,7 @@ binding, and you also require different binding configurations for the transport and HTTP interfaces. `transport.publish_host`:: -(<>) +(<>, string) The network address at which the node can be contacted by other nodes. Accepts an IP address, a hostname, or a <>. Defaults to the address given by `transport.host` or `network.publish_host`. @@ -36,19 +36,19 @@ different addresses for publishing and binding, and you also require different binding configurations for the transport and HTTP interfaces. `transport.publish_port`:: -(<>) +(<>, integer) The port of the <>. Set this parameter only if you need the publish port to be different from `transport.port`. Defaults to the port assigned via `transport.port`. `transport.connect_timeout`:: -(<>) +(<>, <>) The connect timeout for initiating a new connection (in time setting format). Defaults to `30s`. `transport.compress`:: -(<>) +(<>, string) Set to `true`, `indexing_data`, or `false` to configure transport compression between nodes. The option `true` will compress all data. The option `indexing_data` will compress only the raw index data sent between nodes during @@ -56,72 +56,71 @@ ingest, ccr following (excluding bootstrap), and operations based shard recovery (excluding transferring lucene files). Defaults to `indexing_data`. `transport.compression_scheme`:: -(<>) +(<>, string) Configures the compression scheme for `transport.compress`. The options are `deflate` or `lz4`. If `lz4` is configured and the remote node has not been upgraded to a version supporting `lz4`, the traffic will be sent uncompressed. Defaults to `lz4`. `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 -to correctly configure TCP keep-alives instead of using this feature, because -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`. +(<>, <>) +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 to correctly configure +TCP keep-alives instead of using this feature, because TCP keep-alives apply to +all kinds of long-lived connections and not just to transport connections. `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`. +(<>, boolean) +Configures the `SO_KEEPALIVE` option for transport sockets, which determines +whether they send 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, -or the system default otherwise. -This value cannot exceed `300` seconds. In cases where the system default -is higher than `300`, the value is automatically lowered to `300`. Only applicable on -Linux and macOS, and requires Java 11 or newer. +(<>, integer) +Configures the `TCP_KEEPIDLE` option for transport sockets, 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, or the system +default otherwise. This value cannot exceed `300` seconds. In cases where the +system default is higher than `300`, the value is automatically lowered to +`300`. Only applicable on Linux and macOS. `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. -This value cannot exceed `300` seconds. In cases where the system default is higher than `300`, -the value is automatically lowered to `300`. Only applicable on Linux and macOS, -and requires Java 11 or newer. +(<>, integer) +Configures the `TCP_KEEPINTVL` option for transport sockets, which determines +the time in seconds between sending TCP keepalive probes. Defaults to +`network.tcp.keep_interval` if set, or the system default otherwise. This value +cannot exceed `300` seconds. In cases where the system default is higher than +`300`, the value is automatically lowered to `300`. Only applicable on Linux +and macOS. `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` -if set, or the system default otherwise. Only applicable on Linux and macOS, and -requires Java 11 or newer. +(<>, integer) +Configures the `TCP_KEEPCNT` option for transport sockets, 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` if set, or the +system default otherwise. Only applicable on Linux and macOS. + +`transport.tcp.no_delay`:: +(<>, boolean) +Configures the `TCP_NODELAY` option on transport sockets, which determines +whether {wikipedia}/Nagle%27s_algorithm[TCP no delay] is enabled. Defaults to +`true`. `transport.tcp.reuse_address`:: -(<>) -Should an address be reused or not. Defaults to `network.tcp.reuse_address`. +(<>, boolean) +Configures the `SO_REUSEADDR` option for network sockets, which determines +whether the address can 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`. +(<>, <>) +The size of the TCP send buffer for transport traffic. 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`. +(<>, <>) +The size of the TCP receive buffer for transport traffic. Defaults to +`network.tcp.receive_buffer_size`. [[transport-profiles]] ===== Transport profiles