[[modules-http]] === HTTP [[modules-http-description]] // tag::modules-http-description-tag[] The HTTP layer exposes {es}'s REST APIs over HTTP. The HTTP mechanism is completely asynchronous in nature, meaning that there is no blocking thread waiting for a response. The benefit of using asynchronous communication for HTTP is solving the {wikipedia}/C10k_problem[C10k problem]. 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]. // end::modules-http-description-tag[] [http-settings] ==== HTTP settings The following settings can be configured for HTTP. These settings also use the common <>. NOTE: HTTP settings cannot be updated dynamically. You must configure these settings in the {es} <> and restart {es} for changes to take effect. `http.port`:: A bind port range. Defaults to `9200-9300`. `http.publish_port`:: 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`:: The host address to bind the HTTP service to. Defaults to `http.host` (if set) or `network.bind_host`. `http.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`:: Used to set the `http.bind_host` and the `http.publish_host`. `http.max_content_length`:: The max content of an HTTP request. Defaults to `100MB`. `http.max_initial_line_length`:: The max length of an HTTP URL. Defaults to `4KB`. `http.max_header_size`:: The max size of allowed headers. Defaults to `8KB`. [[http-compression]] // tag::http-compression-tag[] `http.compression` {ess-icon}:: 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 https://en.wikipedia.org/wiki/BREACH[BREACH attack]. To compress HTTPS traffic, you must explicitly set `http.compression` to `true`. // end::http-compression-tag[] `http.compression_level`:: 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}:: 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 https://en.wikipedia.org/wiki/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}:: 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}:: 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[] [[http-cors-allow-methods]] // tag::http-cors-allow-methods-tag[] `http.cors.allow-methods` {ess-icon}:: 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}:: 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}:: 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`:: 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. `http.pipelining.max_events`:: 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`. `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 https://en.wikipedia.org/wiki/Nagle%27s_algorithm[TCP no delay] setting. Defaults to `network.tcp.no_delay`. `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`. `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. `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. `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. `http.tcp.reuse_address`:: Should an address be reused or not. Defaults to `network.tcp.reuse_address`. `http.tcp.send_buffer_size`:: The size of the TCP send buffer (specified with <>). 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`. [http-rest-request-tracer] ==== 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`: [source,console] -------------------------------------------------- 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. [source,console] -------------------------------------------------- PUT _cluster/settings { "transient" : { "http.tracer.include" : "*", "http.tracer.exclude" : "" } } --------------------------------------------------