http.asciidoc

HTTP

The HTTP layer exposes {es}'s REST APIs over HTTP. Clients send HTTP requests to a node in the cluster which either handles it locally or else passes it on to other nodes for further processing using the Transport layer.

When possible, consider using {wikipedia}/Keepalive#HTTP_Keepalive[HTTP keep alive] when connecting for better performance and try to get your favorite client not to do {wikipedia}/Chunked_transfer_encoding[HTTP chunking].

HTTP settings

The following settings can be configured for HTTP. These settings also use the common network settings.

http.port

(Static) A bind port range. Defaults to 9200-9300.

http.publish_port

(Static) The port that HTTP clients should use when communicating with this node. Useful when a cluster node is behind a proxy or firewall and the http.port is not directly addressable from the outside. Defaults to the actual port assigned via http.port.

http.bind_host

(Static) The host address to bind the HTTP service to. Defaults to http.host (if set) or network.bind_host.

http.publish_host

(Static) The host address to publish for HTTP clients to connect to. Defaults to http.host (if set) or network.publish_host.

http.host

(Static) Used to set the http.bind_host and the http.publish_host.

http.max_content_length

(Static) Maximum length of an HTTP request body. Defaults to 100MB.

http.max_initial_line_length

(Static) The max length of an HTTP URL. Defaults to 4KB.

http.max_header_size

(Static) The max size of allowed headers. Defaults to 8KB.

http.compression {ess-icon}

(Static) 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.

http.compression_level

(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.

http.cors.enabled {ess-icon}

(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 {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.

http.cors.allow-origin {ess-icon}

(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.

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.

http.cors.max-age {ess-icon}

(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).

http.cors.allow-methods {ess-icon}

(Static) Which methods to allow. Defaults to OPTIONS, HEAD, GET, POST, PUT, DELETE.

http.cors.allow-headers {ess-icon}

(Static) Which headers to allow. Defaults to X-Requested-With, Content-Type, Content-Length.

http.cors.allow-credentials {ess-icon}

(Static) 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.

http.detailed_errors.enabled

(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 enable stack traces and return detailed error messages. Otherwise, only a simple message will be returned.

http.pipelining.max_events

(Static) 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) The maximum number of warning headers in client HTTP responses. Defaults to unbounded.

http.max_warning_header_size

(Static) The maximum total size of warning headers in client HTTP responses. Defaults to unbounded.

http.tcp.no_delay

(Static) Enable or disable the {wikipedia}/Nagle%27s_algorithm[TCP no delay] setting. Defaults to network.tcp.no_delay.

http.tcp.keep_alive

(Static) 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) 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.

http.tcp.keep_interval

(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.

http.tcp.keep_count

(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.

http.tcp.reuse_address

(Static) Should an address be reused or not. Defaults to network.tcp.reuse_address.

http.tcp.send_buffer_size

(Static) The size of the TCP send buffer (specified with size units). Defaults to network.tcp.send_buffer_size.

http.tcp.receive_buffer_size

(Static) The size of the TCP receive buffer (specified with size units). Defaults to network.tcp.receive_buffer_size.

REST request tracer

The HTTP layer has a dedicated tracer logger which, when activated, logs incoming requests. The log can be dynamically activated by setting the level of the org.elasticsearch.http.HttpTracer logger to TRACE:

PUT _cluster/settings
{
   "transient" : {
      "logger.org.elasticsearch.http.HttpTracer" : "TRACE"
   }
}

You can also control which uris will be traced, using a set of include and exclude wildcard patterns. By default every request will be traced.

PUT _cluster/settings
{
   "transient" : {
      "http.tracer.include" : "*",
      "http.tracer.exclude" : ""
   }
}