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

[DOCS] Document static HTTP settings (#61429) (#61536)

This commit is contained in:
James Rodewig 2020-08-25 11:27:05 -04:00 committed by GitHub
parent 5ad0ce49e1
commit e3d23c34ab
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 31 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -17,39 +17,45 @@ client not to do {wikipedia}/Chunked_transfer_encoding[HTTP chunking].
The following settings can be configured for HTTP. These settings also use the common <<modules-network,network settings>>. The following settings can be configured for HTTP. These settings also use the common <<modules-network,network settings>>.
NOTE: HTTP settings cannot be updated dynamically. You must configure these settings in the {es} <<settings, configuration file>>
and restart {es} for changes to take effect.
`http.port`:: `http.port`::
(<<static-cluster-setting,Static>>)
A bind port range. Defaults to `9200-9300`. A bind port range. Defaults to `9200-9300`.
`http.publish_port`:: `http.publish_port`::
(<<static-cluster-setting,Static>>)
The port that HTTP clients should use when The port that HTTP clients should use when
communicating with this node. Useful when a cluster node is behind a communicating with this node. Useful when a cluster node is behind a
proxy or firewall and the `http.port` is not directly addressable proxy or firewall and the `http.port` is not directly addressable
from the outside. Defaults to the actual port assigned via `http.port`. from the outside. Defaults to the actual port assigned via `http.port`.
`http.bind_host`:: `http.bind_host`::
(<<static-cluster-setting,Static>>)
The host address to bind the HTTP service to. Defaults to `http.host` (if set) or `network.bind_host`. The host address to bind the HTTP service to. Defaults to `http.host` (if set) or `network.bind_host`.
`http.publish_host`:: `http.publish_host`::
(<<static-cluster-setting,Static>>)
The host address to publish for HTTP clients to connect to. Defaults to `http.host` (if set) or `network.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`:: `http.host`::
(<<static-cluster-setting,Static>>)
Used to set the `http.bind_host` and the `http.publish_host`. Used to set the `http.bind_host` and the `http.publish_host`.
`http.max_content_length`:: `http.max_content_length`::
(<<static-cluster-setting,Static>>)
The max content of an HTTP request. Defaults to `100MB`. The max content of an HTTP request. Defaults to `100MB`.
`http.max_initial_line_length`:: `http.max_initial_line_length`::
(<<static-cluster-setting,Static>>)
The max length of an HTTP URL. Defaults to `4KB`. The max length of an HTTP URL. Defaults to `4KB`.
`http.max_header_size`:: `http.max_header_size`::
(<<static-cluster-setting,Static>>)
The max size of allowed headers. Defaults to `8KB`. The max size of allowed headers. Defaults to `8KB`.
[[http-compression]] [[http-compression]]
// tag::http-compression-tag[] // tag::http-compression-tag[]
`http.compression` {ess-icon}:: `http.compression` {ess-icon}::
(<<static-cluster-setting,Static>>)
Support for compression when possible (with Accept-Encoding). If HTTPS is enabled, defaults to `false`. Otherwise, defaults to `true`. 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 Disabling compression for HTTPS mitigates potential security risks, such as a
@ -58,11 +64,13 @@ you must explicitly set `http.compression` to `true`.
// end::http-compression-tag[] // end::http-compression-tag[]
`http.compression_level`:: `http.compression_level`::
(<<static-cluster-setting,Static>>)
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`. 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]] [[http-cors-enabled]]
// tag::http-cors-enabled-tag[] // tag::http-cors-enabled-tag[]
`http.cors.enabled` {ess-icon}:: `http.cors.enabled` {ess-icon}::
(<<static-cluster-setting,Static>>)
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 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. {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. {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.
@ -76,6 +84,7 @@ compromised. If CORS is not enabled on {es}, the only way for the client to know
[[http-cors-allow-origin]] [[http-cors-allow-origin]]
// tag::http-cors-allow-origin-tag[] // tag::http-cors-allow-origin-tag[]
`http.cors.allow-origin` {ess-icon}:: `http.cors.allow-origin` {ess-icon}::
(<<static-cluster-setting,Static>>)
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. 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*. 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*.
@ -85,24 +94,28 @@ IMPORTANT: A wildcard (`*`) is a valid value but is considered a security risk,
[[http-cors-max-age]] [[http-cors-max-age]]
// tag::http-cors-max-age-tag[] // tag::http-cors-max-age-tag[]
`http.cors.max-age` {ess-icon}:: `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). 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[] // end::http-cors-max-age-tag[]
[[http-cors-allow-methods]] [[http-cors-allow-methods]]
// tag::http-cors-allow-methods-tag[] // tag::http-cors-allow-methods-tag[]
`http.cors.allow-methods` {ess-icon}:: `http.cors.allow-methods` {ess-icon}::
(<<static-cluster-setting,Static>>)
Which methods to allow. Defaults to `OPTIONS, HEAD, GET, POST, PUT, DELETE`. Which methods to allow. Defaults to `OPTIONS, HEAD, GET, POST, PUT, DELETE`.
// end::http-cors-allow-methods-tag[] // end::http-cors-allow-methods-tag[]
[[http-cors-allow-headers]] [[http-cors-allow-headers]]
// tag::http-cors-allow-headers-tag[] // tag::http-cors-allow-headers-tag[]
`http.cors.allow-headers` {ess-icon}:: `http.cors.allow-headers` {ess-icon}::
(<<static-cluster-setting,Static>>)
Which headers to allow. Defaults to `X-Requested-With, Content-Type, Content-Length`. Which headers to allow. Defaults to `X-Requested-With, Content-Type, Content-Length`.
// end::http-cors-allow-headers-tag[] // end::http-cors-allow-headers-tag[]
[[http-cors-allow-credentials]] [[http-cors-allow-credentials]]
// tag::http-cors-allow-credentials-tag[] // tag::http-cors-allow-credentials-tag[]
`http.cors.allow-credentials` {ess-icon}:: `http.cors.allow-credentials` {ess-icon}::
(<<static-cluster-setting,Static>>)
Whether the `Access-Control-Allow-Credentials` header should be returned. Defaults to `false`. 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`. NOTE: This header is only returned when the setting is set to `true`.
@ -110,54 +123,66 @@ NOTE: This header is only returned when the setting is set to `true`.
// end::http-cors-allow-credentials-tag[] // end::http-cors-allow-credentials-tag[]
`http.detailed_errors.enabled`:: `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 `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. 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`:: `http.pipelining.max_events`::
(<<static-cluster-setting,Static>>)
The maximum number of events to be queued up in memory before an HTTP connection is closed, defaults to `10000`. 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`:: `http.max_warning_header_count`::
(<<static-cluster-setting,Static>>)
The maximum number of warning headers in client HTTP responses. Defaults to `unbounded`. The maximum number of warning headers in client HTTP responses. Defaults to `unbounded`.
`http.max_warning_header_size`:: `http.max_warning_header_size`::
(<<static-cluster-setting,Static>>)
The maximum total size of warning headers in client HTTP responses. Defaults to `unbounded`. The maximum total size of warning headers in client HTTP responses. Defaults to `unbounded`.
`http.tcp.no_delay`:: `http.tcp.no_delay`::
(<<static-cluster-setting,Static>>)
Enable or disable the {wikipedia}/Nagle%27s_algorithm[TCP no delay] Enable or disable the {wikipedia}/Nagle%27s_algorithm[TCP no delay]
setting. Defaults to `network.tcp.no_delay`. setting. Defaults to `network.tcp.no_delay`.
`http.tcp.keep_alive`:: `http.tcp.keep_alive`::
(<<static-cluster-setting,Static>>)
Configures the `SO_KEEPALIVE` option for this socket, which Configures the `SO_KEEPALIVE` option for this socket, which
determines whether it sends TCP keepalive probes. determines whether it sends TCP keepalive probes.
Defaults to `network.tcp.keep_alive`. Defaults to `network.tcp.keep_alive`.
`http.tcp.keep_idle`:: Configures the `TCP_KEEPIDLE` option for this socket, which `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 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 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 uses the system default. This value cannot exceed `300` seconds. Only applicable on
Linux and macOS, and requires Java 11 or newer. Linux and macOS, and requires Java 11 or newer.
`http.tcp.keep_interval`:: Configures the `TCP_KEEPINTVL` option for this socket, `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. which determines the time in seconds between sending TCP keepalive probes.
Defaults to `network.tcp.keep_interval`, which uses the system default. 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 This value cannot exceed `300` seconds. Only applicable on Linux and macOS, and requires
Java 11 or newer. Java 11 or newer.
`http.tcp.keep_count`:: Configures the `TCP_KEEPCNT` option for this socket, which `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 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`, 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 which uses the system default. Only applicable on Linux and macOS, and
requires Java 11 or newer. requires Java 11 or newer.
`http.tcp.reuse_address`:: `http.tcp.reuse_address`::
(<<static-cluster-setting,Static>>)
Should an address be reused or not. Defaults to `network.tcp.reuse_address`. Should an address be reused or not. Defaults to `network.tcp.reuse_address`.
`http.tcp.send_buffer_size`:: `http.tcp.send_buffer_size`::
(<<static-cluster-setting,Static>>)
The size of the TCP send buffer (specified with <<size-units,size units>>). The size of the TCP send buffer (specified with <<size-units,size units>>).
Defaults to `network.tcp.send_buffer_size`. Defaults to `network.tcp.send_buffer_size`.
`http.tcp.receive_buffer_size`:: `http.tcp.receive_buffer_size`::
(<<static-cluster-setting,Static>>)
The size of the TCP receive buffer (specified with <<size-units,size units>>). The size of the TCP receive buffer (specified with <<size-units,size units>>).
Defaults to `network.tcp.receive_buffer_size`. Defaults to `network.tcp.receive_buffer_size`.