http.asciidoc 8.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196
  1. [[modules-http]]
  2. === HTTP
  3. [[modules-http-description]]
  4. // tag::modules-http-description-tag[]
  5. The HTTP layer exposes {es}'s REST APIs over HTTP.
  6. The HTTP mechanism is completely asynchronous in nature, meaning that
  7. there is no blocking thread waiting for a response. The benefit of using
  8. asynchronous communication for HTTP is solving the
  9. {wikipedia}/C10k_problem[C10k problem].
  10. When possible, consider using
  11. {wikipedia}/Keepalive#HTTP_Keepalive[HTTP keep alive]
  12. when connecting for better performance and try to get your favorite
  13. client not to do
  14. {wikipedia}/Chunked_transfer_encoding[HTTP chunking].
  15. // end::modules-http-description-tag[]
  16. [http-settings]
  17. ==== HTTP settings
  18. The following settings can be configured for HTTP. These settings also use the common <<modules-network,network settings>>.
  19. NOTE: HTTP settings cannot be updated dynamically. You must configure these settings in the {es} <<settings, configuration file>>
  20. and restart {es} for changes to take effect.
  21. `http.port`::
  22. A bind port range. Defaults to `9200-9300`.
  23. `http.publish_port`::
  24. The port that HTTP clients should use when
  25. communicating with this node. Useful when a cluster node is behind a
  26. proxy or firewall and the `http.port` is not directly addressable
  27. from the outside. Defaults to the actual port assigned via `http.port`.
  28. `http.bind_host`::
  29. The host address to bind the HTTP service to. Defaults to `http.host` (if set) or `network.bind_host`.
  30. `http.publish_host`::
  31. The host address to publish for HTTP clients to connect to. Defaults to `http.host` (if set) or `network.publish_host`.
  32. `http.host`::
  33. Used to set the `http.bind_host` and the `http.publish_host`.
  34. `http.max_content_length`::
  35. The max content of an HTTP request. Defaults to `100MB`.
  36. `http.max_initial_line_length`::
  37. The max length of an HTTP URL. Defaults to `4KB`.
  38. `http.max_header_size`::
  39. The max size of allowed headers. Defaults to `8KB`.
  40. [[http-compression]]
  41. // tag::http-compression-tag[]
  42. `http.compression` {ess-icon}::
  43. Support for compression when possible (with Accept-Encoding). If HTTPS is enabled, defaults to `false`. Otherwise, defaults to `true`.
  44. +
  45. Disabling compression for HTTPS mitigates potential security risks, such as a
  46. https://en.wikipedia.org/wiki/BREACH[BREACH attack]. To compress HTTPS traffic,
  47. you must explicitly set `http.compression` to `true`.
  48. // end::http-compression-tag[]
  49. `http.compression_level`::
  50. 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`.
  51. [[http-cors-enabled]]
  52. // tag::http-cors-enabled-tag[]
  53. `http.cors.enabled` {ess-icon}::
  54. 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
  55. https://en.wikipedia.org/wiki/Cross-origin_resource_sharing[CORS] requests.
  56. {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.
  57. +
  58. 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
  59. `Access-Control-Allow-Origin` response header, then cross-origin security is
  60. 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.
  61. // end::http-cors-enabled-tag[]
  62. [[http-cors-allow-origin]]
  63. // tag::http-cors-allow-origin-tag[]
  64. `http.cors.allow-origin` {ess-icon}::
  65. 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.
  66. +
  67. 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*.
  68. // end::http-cors-allow-origin-tag[]
  69. [[http-cors-max-age]]
  70. // tag::http-cors-max-age-tag[]
  71. `http.cors.max-age` {ess-icon}::
  72. 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).
  73. // end::http-cors-max-age-tag[]
  74. [[http-cors-allow-methods]]
  75. // tag::http-cors-allow-methods-tag[]
  76. `http.cors.allow-methods` {ess-icon}::
  77. Which methods to allow. Defaults to `OPTIONS, HEAD, GET, POST, PUT, DELETE`.
  78. // end::http-cors-allow-methods-tag[]
  79. [[http-cors-allow-headers]]
  80. // tag::http-cors-allow-headers-tag[]
  81. `http.cors.allow-headers` {ess-icon}::
  82. Which headers to allow. Defaults to `X-Requested-With, Content-Type, Content-Length`.
  83. // end::http-cors-allow-headers-tag[]
  84. [[http-cors-allow-credentials]]
  85. // tag::http-cors-allow-credentials-tag[]
  86. `http.cors.allow-credentials` {ess-icon}::
  87. Whether the `Access-Control-Allow-Credentials` header should be returned. Defaults to `false`.
  88. +
  89. NOTE: This header is only returned when the setting is set to `true`.
  90. // end::http-cors-allow-credentials-tag[]
  91. `http.detailed_errors.enabled`::
  92. If `true`, enables the output of detailed error messages and stack traces in the response output. Defaults to `true`.
  93. +
  94. 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.
  95. `http.pipelining.max_events`::
  96. The maximum number of events to be queued up in memory before an HTTP connection is closed, defaults to `10000`.
  97. `http.max_warning_header_count`::
  98. The maximum number of warning headers in client HTTP responses. Defaults to `unbounded`.
  99. `http.max_warning_header_size`::
  100. The maximum total size of warning headers in client HTTP responses. Defaults to `unbounded`.
  101. `http.tcp.no_delay`::
  102. Enable or disable the https://en.wikipedia.org/wiki/Nagle%27s_algorithm[TCP no delay]
  103. setting. Defaults to `network.tcp.no_delay`.
  104. `http.tcp.keep_alive`::
  105. Configures the `SO_KEEPALIVE` option for this socket, which
  106. determines whether it sends TCP keepalive probes.
  107. Defaults to `network.tcp.keep_alive`.
  108. `http.tcp.keep_idle`:: Configures the `TCP_KEEPIDLE` option for this socket, which
  109. determines the time in seconds that a connection must be idle before
  110. starting to send TCP keepalive probes. Defaults to `network.tcp.keep_idle`, which
  111. uses the system default. This value cannot exceed `300` seconds. Only applicable on
  112. Linux and macOS, and requires Java 11 or newer.
  113. `http.tcp.keep_interval`:: Configures the `TCP_KEEPINTVL` option for this socket,
  114. which determines the time in seconds between sending TCP keepalive probes.
  115. Defaults to `network.tcp.keep_interval`, which uses the system default.
  116. This value cannot exceed `300` seconds. Only applicable on Linux and macOS, and requires
  117. Java 11 or newer.
  118. `http.tcp.keep_count`:: Configures the `TCP_KEEPCNT` option for this socket, which
  119. determines the number of unacknowledged TCP keepalive probes that may be
  120. sent on a connection before it is dropped. Defaults to `network.tcp.keep_count`,
  121. which uses the system default. Only applicable on Linux and macOS, and
  122. requires Java 11 or newer.
  123. `http.tcp.reuse_address`::
  124. Should an address be reused or not. Defaults to `network.tcp.reuse_address`.
  125. `http.tcp.send_buffer_size`::
  126. The size of the TCP send buffer (specified with <<size-units,size units>>).
  127. Defaults to `network.tcp.send_buffer_size`.
  128. `http.tcp.receive_buffer_size`::
  129. The size of the TCP receive buffer (specified with <<size-units,size units>>).
  130. Defaults to `network.tcp.receive_buffer_size`.
  131. [http-rest-request-tracer]
  132. ==== REST request tracer
  133. The HTTP layer has a dedicated tracer logger which, when activated, logs incoming requests. The log can be dynamically activated
  134. by setting the level of the `org.elasticsearch.http.HttpTracer` logger to `TRACE`:
  135. [source,console]
  136. --------------------------------------------------
  137. PUT _cluster/settings
  138. {
  139. "transient" : {
  140. "logger.org.elasticsearch.http.HttpTracer" : "TRACE"
  141. }
  142. }
  143. --------------------------------------------------
  144. You can also control which uris will be traced, using a set of include and exclude wildcard patterns. By default every request will be
  145. traced.
  146. [source,console]
  147. --------------------------------------------------
  148. PUT _cluster/settings
  149. {
  150. "transient" : {
  151. "http.tracer.include" : "*",
  152. "http.tracer.exclude" : ""
  153. }
  154. }
  155. --------------------------------------------------