elasticsearch/docs/reference/modules/http.asciidoc

[[http-settings]]
==== Advanced HTTP settings

Use the following advanced settings to configure the HTTP interface
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>>, 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>>.
Use this setting only if you require different configurations for the
transport and HTTP interfaces.
+
Defaults to the address given by `network.host`. However, note that
<<configuring-stack-security,security auto-configuration>> will add
`http.host: 0.0.0.0` to your `elasticsearch.yml` configuration file, which
overrides this default.

`http.bind_host`::
(<<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
`http.host` or `network.bind_host`. Use this setting only if you require to
bind to multiple addresses or to use different addresses for publishing and
binding, and you also require different binding configurations for the
transport and HTTP interfaces.

`http.publish_host`::
(<<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
`network.publish_host`. Use this setting only if you require to bind to
multiple addresses or to use different addresses for publishing and binding,
and you also require different binding configurations for the transport and
HTTP interfaces.

`http.publish_port`::
(<<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>>, <<byte-units,byte value>>)
Maximum size of an HTTP request body. If the body is compressed, the limit applies
to the HTTP request body size before compression. Defaults to `100mb`. Configuring 
this setting to greater than `100mb` can cause cluster instability and is not
recommended. If you hit this limit when sending a request to the <<docs-bulk>>
API, configure your client to send fewer documents in each bulk request. If you
wish to index individual documents that exceed `100mb`, pre-process them into
smaller documents before sending them to {es}. For instance, store the raw data
in a system outside {es} and include a link to the raw data in the documents
that {es} indexes.

`http.max_initial_line_length`::
(<<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>>, <<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>>, 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
{wikipedia}/BREACH[BREACH attack]. To compress HTTPS traffic,
you must explicitly set `http.compression` to `true`.
// end::http-compression-tag[]

`http.compression_level`::
(<<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>>, 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.
+
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
`Access-Control-Allow-Origin` response header, then cross-origin security is
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.

// end::http-cors-enabled-tag[]

[[http-cors-allow-origin]]
// tag::http-cors-allow-origin-tag[]
`http.cors.allow-origin` {ess-icon}::
(<<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*.

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

[[http-cors-max-age]]
// tag::http-cors-max-age-tag[]
`http.cors.max-age` {ess-icon}::
(<<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>>, 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>>, string)
Which headers to allow. Defaults to `X-Requested-With, Content-Type, Content-Length, Authorization, Accept, User-Agent, X-Elastic-Client-Meta`.
// end::http-cors-allow-headers-tag[]

[[http-cors-expose-headers]]
// tag::http-cors-expose-headers-tag[]
`http.cors.expose-headers` {ess-icon}::
(<<static-cluster-setting,Static>>)
Which response headers to expose in the client. Defaults to `X-elastic-product`.
// end::http-cors-expose-headers-tag[]

[[http-cors-allow-credentials]]
// tag::http-cors-allow-credentials-tag[]
`http.cors.allow-credentials` {ess-icon}::
(<<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>>, boolean)
Configures whether detailed error reporting in HTTP responses is enabled.
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.
If set to `false`, requests with the `?error_trace` parameter are rejected.

`http.pipelining.max_events`::
(<<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>>, 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>>, <<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>>, 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`::
(<<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>>, 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>>, 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>>, 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>>, <<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>>, <<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>>, boolean)
Enable or disable collection of HTTP client stats. Defaults to `true`.

`http.client_stats.closed_channels.max_count`::
(<<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>>, <<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`.

===== HTTP client configuration

Many HTTP clients and proxies are configured for browser-like response latency
and impose a fairly short timeout by default, reporting a failure if {es} takes
longer than this timeout to complete the processing of a request. {es} will
always eventually respond to every request, but some requests may require many
minutes of processing time to complete. Consider carefully whether your
client's default response timeout is appropriate for your needs. In many cases
it is better to wait longer for a response instead of failing, and this means
you should disable any response timeouts:

* If you react to a timeout by retrying the request, the retry will often end
up being placed at the back of the same queue which held the original request.
It will therefore take longer to complete the processing of the request if you
time out and retry instead of waiting more patiently. Retrying also imposes
additional load on {es}.

* If a request is not idempotent and cannot be retried then failing the request
is your last resort. Waiting more patiently for a response will usually allow
the overall operation to succeed.

If you disable the response timeout in your client, make sure to configure TCP
keepalives instead. TCP keepalives are the recommended way to prevent a client
from waiting indefinitely in the event of a network outage.