Skip to content

Clean up network setting docs #88929

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Aug 1, 2022
Merged

Clean up network setting docs #88929

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
23427f4
Clean up network setting docs
DaveCTurner Jul 29, 2022
3de4b8b
Fix docs for `http.detailed_errors.enabled`
DaveCTurner Jul 29, 2022
72be4ee
Rework detailed_errors docs
DaveCTurner Jul 29, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 68 additions & 60 deletions docs/reference/modules/http.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ independently of the <<transport-settings,transport interface>>. You can also
configure both interfaces together using the <<common-network-settings,network settings>>.

`http.host`::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, 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 <<network-interface-values,special value>>.
Expand All @@ -16,7 +16,7 @@ transport and HTTP interfaces.
Defaults to the address given by `network.host`.

`http.bind_host`::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, 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
<<network-interface-values,special values>>. Defaults to the address given by
Expand All @@ -26,7 +26,7 @@ binding, and you also require different binding configurations for the
transport and HTTP interfaces.

`http.publish_host`::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, string)
The network address for HTTP clients to contact the node using sniffing.
Accepts an IP address, a hostname, or a <<network-interface-values,special
value>>. Defaults to the address given by `http.host` or
Expand All @@ -36,27 +36,27 @@ and you also require different binding configurations for the transport and
HTTP interfaces.

`http.publish_port`::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, integer)
The port of the <<modules-network-binding-publishing,HTTP publish address>>.
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`::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, <<byte-units,byte value>>)
Maximum size of an HTTP request body. Defaults to `100mb`.

`http.max_initial_line_length`::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, <<byte-units,byte value>>)
Maximum size of an HTTP URL. Defaults to `4kb`.

`http.max_header_size`::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, <<byte-units,byte value>>)
Maximum size of allowed headers. Defaults to `16kb`.

[[http-compression]]
// tag::http-compression-tag[]
`http.compression` {ess-icon}::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, 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
Expand All @@ -65,13 +65,13 @@ you must explicitly set `http.compression` to `true`.
// end::http-compression-tag[]

`http.compression_level`::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, 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}::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, 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.
Expand All @@ -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}::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, 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*.
Expand All @@ -95,109 +95,117 @@ 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}::
(<<static-cluster-setting,Static>>)
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).
(<<static-cluster-setting,Static>>, 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}::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, 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}::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, 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}::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, 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`.

// end::http-cors-allow-credentials-tag[]

`http.detailed_errors.enabled`::
(<<static-cluster-setting,Static>>)
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.
(<<static-cluster-setting,Static>>, boolean)
Configures whether detailed errors may be returned in HTTP responses. Defaults
to `true`, which means that HTTP requests which include
<<common-options-error-options,`?error_trace` URI parameter>> will return a
detailed error message including a stack trace if they encounter an exception.
Copy link
Contributor

@lockewritesdocs lockewritesdocs Jul 29, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Configures whether detailed errors may be returned in HTTP responses. Defaults
to `true`, which means that HTTP requests which include
<<common-options-error-options,`?error_trace` URI parameter>> will return a
detailed error message including a stack trace if they encounter an exception.
Configures whether detailed errors are returned in HTTP responses. Defaults
to `true`, which means that HTTP requests that include the
<<common-options-error-options,`?error_trace`>> parameter will return a
detailed error message including a stack trace if they encounter an exception.

Copy link
Contributor Author

@DaveCTurner DaveCTurner Jul 29, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think may be is correct here. By default we don't return detailed errors even if http.detailed_errors.enabled: true - this setting just permits the use of the ?error_trace parameter.

Copy link
Contributor Author

@DaveCTurner DaveCTurner Jul 29, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See 72be4ee for an alternative.

If set to `false`, requests with the `?error_trace` parameter are rejected.

`http.pipelining.max_events`::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, 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`::
(<<static-cluster-setting,Static>>)
The maximum number of warning headers in client HTTP responses. Defaults to `unbounded`.
(<<static-cluster-setting,Static>>, 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`::
(<<static-cluster-setting,Static>>)
The maximum total size of warning headers in client HTTP responses. Defaults to `unbounded`.

`http.tcp.no_delay`::
(<<static-cluster-setting,Static>>)
Enable or disable the {wikipedia}/Nagle%27s_algorithm[TCP no delay]
setting. Defaults to `network.tcp.no_delay`.
(<<static-cluster-setting,Static>>, <<byte-units,byte value>>)
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`::
(<<static-cluster-setting,Static>>)
Configures the `SO_KEEPALIVE` option for this socket, which
determines whether it sends TCP keepalive probes.
Defaults to `network.tcp.keep_alive`.
(<<static-cluster-setting,Static>>, boolean)
Configures the `SO_KEEPALIVE` option for this socket, which determines whether
it sends TCP keepalive probes. Defaults to `network.tcp.keep_alive`.
Copy link
Contributor

@lockewritesdocs lockewritesdocs Jul 29, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
it sends TCP keepalive probes. Defaults to `network.tcp.keep_alive`.
it sends TCP keepalive probes. Defaults to `true`.

Copy link
Contributor

@lockewritesdocs lockewritesdocs Jul 29, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a boolean setting, which I believe defaults to true.


`http.tcp.keep_idle`::
(<<static-cluster-setting,Static>>) 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.
(<<static-cluster-setting,Static>>, 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`::
(<<static-cluster-setting,Static>>) 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.
(<<static-cluster-setting,Static>>, 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`::
(<<static-cluster-setting,Static>>) 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.
(<<static-cluster-setting,Static>>, 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`::
(<<static-cluster-setting,Static>>, 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`::
(<<static-cluster-setting,Static>>)
Should an address be reused or not. Defaults to `network.tcp.reuse_address`.
(<<static-cluster-setting,Static>>, 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`::
(<<static-cluster-setting,Static>>)
The size of the TCP send buffer (specified with <<size-units,size units>>).
Defaults to `network.tcp.send_buffer_size`.
(<<static-cluster-setting,Static>>, <<byte-units,byte value>>)
The size of the TCP send buffer for HTTP traffic. Defaults to
`network.tcp.send_buffer_size`.

`http.tcp.receive_buffer_size`::
(<<static-cluster-setting,Static>>)
The size of the TCP receive buffer (specified with <<size-units,size units>>).
Defaults to `network.tcp.receive_buffer_size`.
(<<static-cluster-setting,Static>>, <<byte-units,byte value>>)
The size of the TCP receive buffer for HTTP traffic. Defaults to
`network.tcp.receive_buffer_size`.

`http.client_stats.enabled`::
(<<dynamic-cluster-setting,Dynamic>>)
(<<dynamic-cluster-setting,Dynamic>>, boolean)
Enable or disable collection of HTTP client stats. Defaults to `true`.

`http.client_stats.closed_channels.max_count`::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, 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`::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, <<time-units,time value>>)
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`.
78 changes: 39 additions & 39 deletions docs/reference/modules/network.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,23 +38,23 @@ proceeding.
Most users will need to configure only the following network settings.

`network.host`::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, 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 <<network-interface-values,special value>>.
+
Defaults to `_local_`.

`http.port`::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, 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.
+
Defaults to `9200-9300`.

`transport.port`::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, 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
Expand Down Expand Up @@ -170,15 +170,15 @@ you should not use them if you can use the <<common-network-settings,commonly
used settings>> instead.

`network.bind_host`::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, 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
<<network-interface-values,special values>>. Defaults to the address given by
`network.host`. Use this setting only if binding to multiple addresses or using
different addresses for publishing and binding.

`network.publish_host`::
(<<static-cluster-setting,Static>>)
(<<static-cluster-setting,Static>>, string)
The network address that clients and other nodes can use to contact this node.
Accepts an IP address, a hostname, or a <<network-interface-values,special
value>>. Defaults to the address given by `network.host`. Use this setting only
Expand All @@ -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`::
(<<static-cluster-setting,Static>>)
Enable or disable the {wikipedia}/Nagle%27s_algorithm[TCP no delay]
setting. Defaults to `true`.

`network.tcp.keep_alive`::
(<<static-cluster-setting,Static>>)
Configures the `SO_KEEPALIVE` option for this socket, which
determines whether it sends TCP keepalive probes.
(<<static-cluster-setting,Static>>, 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`::
(<<static-cluster-setting,Static>>)
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.
(<<static-cluster-setting,Static>>, 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`::
(<<static-cluster-setting,Static>>)
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.
(<<static-cluster-setting,Static>>, 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`::
(<<static-cluster-setting,Static>>)
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.
(<<static-cluster-setting,Static>>, 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`::
(<<static-cluster-setting,Static>>, 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`::
(<<static-cluster-setting,Static>>)
Should an address be reused or not. Defaults to `true` on non-windows
machines.
(<<static-cluster-setting,Static>>, 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`::
(<<static-cluster-setting,Static>>)
The size of the TCP send buffer (specified with <<size-units,size units>>).
By default not explicitly set.
(<<static-cluster-setting,Static>>, <<byte-units,byte value>>)
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`::
(<<static-cluster-setting,Static>>)
The size of the TCP receive buffer (specified with <<size-units,size units>>).
By default not explicitly set.
(<<static-cluster-setting,Static>>, <<byte-units,byte value>>)
Configures the size of the TCP receive buffer. Defaults to `-1` which means to
use the system default.

include::http.asciidoc[]

Expand Down
Loading