Skip to content

Commit 23427f4

Browse files
Clean up network setting docs
- Add types for all params - Remove mention of JDKs before 11 - Clarify some wording Co-authored-by: Stef Nestor <[email protected]>
1 parent 9f7caba commit 23427f4

File tree

3 files changed

+153
-148
lines changed

3 files changed

+153
-148
lines changed

docs/reference/modules/http.asciidoc

Lines changed: 63 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ independently of the <<transport-settings,transport interface>>. You can also
66
configure both interfaces together using the <<common-network-settings,network settings>>.
77

88
`http.host`::
9-
(<<static-cluster-setting,Static>>)
9+
(<<static-cluster-setting,Static>>, string)
1010
Sets the address of this node for HTTP traffic. The node will bind to this
1111
address and will also use it as its HTTP publish address. Accepts an IP
1212
address, a hostname, or a <<network-interface-values,special value>>.
@@ -16,7 +16,7 @@ transport and HTTP interfaces.
1616
Defaults to the address given by `network.host`.
1717

1818
`http.bind_host`::
19-
(<<static-cluster-setting,Static>>)
19+
(<<static-cluster-setting,Static>>, string)
2020
The network address(es) to which the node should bind in order to listen for
2121
incoming HTTP connections. Accepts a list of IP addresses, hostnames, and
2222
<<network-interface-values,special values>>. Defaults to the address given by
@@ -26,7 +26,7 @@ binding, and you also require different binding configurations for the
2626
transport and HTTP interfaces.
2727

2828
`http.publish_host`::
29-
(<<static-cluster-setting,Static>>)
29+
(<<static-cluster-setting,Static>>, string)
3030
The network address for HTTP clients to contact the node using sniffing.
3131
Accepts an IP address, a hostname, or a <<network-interface-values,special
3232
value>>. Defaults to the address given by `http.host` or
@@ -36,27 +36,27 @@ and you also require different binding configurations for the transport and
3636
HTTP interfaces.
3737

3838
`http.publish_port`::
39-
(<<static-cluster-setting,Static>>)
39+
(<<static-cluster-setting,Static>>, integer)
4040
The port of the <<modules-network-binding-publishing,HTTP publish address>>.
4141
Configure this setting only if you need the publish port to be different from
4242
`http.port`. Defaults to the port assigned via `http.port`.
4343

4444
`http.max_content_length`::
45-
(<<static-cluster-setting,Static>>)
45+
(<<static-cluster-setting,Static>>, <<byte-units,byte value>>)
4646
Maximum size of an HTTP request body. Defaults to `100mb`.
4747

4848
`http.max_initial_line_length`::
49-
(<<static-cluster-setting,Static>>)
49+
(<<static-cluster-setting,Static>>, <<byte-units,byte value>>)
5050
Maximum size of an HTTP URL. Defaults to `4kb`.
5151

5252
`http.max_header_size`::
53-
(<<static-cluster-setting,Static>>)
53+
(<<static-cluster-setting,Static>>, <<byte-units,byte value>>)
5454
Maximum size of allowed headers. Defaults to `16kb`.
5555

5656
[[http-compression]]
5757
// tag::http-compression-tag[]
5858
`http.compression` {ess-icon}::
59-
(<<static-cluster-setting,Static>>)
59+
(<<static-cluster-setting,Static>>, boolean)
6060
Support for compression when possible (with Accept-Encoding). If HTTPS is enabled, defaults to `false`. Otherwise, defaults to `true`.
6161
+
6262
Disabling compression for HTTPS mitigates potential security risks, such as a
@@ -65,13 +65,13 @@ you must explicitly set `http.compression` to `true`.
6565
// end::http-compression-tag[]
6666

6767
`http.compression_level`::
68-
(<<static-cluster-setting,Static>>)
68+
(<<static-cluster-setting,Static>>, integer)
6969
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`.
7070

7171
[[http-cors-enabled]]
7272
// tag::http-cors-enabled-tag[]
7373
`http.cors.enabled` {ess-icon}::
74-
(<<static-cluster-setting,Static>>)
74+
(<<static-cluster-setting,Static>>, boolean)
7575
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
7676
{wikipedia}/Cross-origin_resource_sharing[CORS] requests.
7777
{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.
@@ -85,7 +85,7 @@ compromised. If CORS is not enabled on {es}, the only way for the client to know
8585
[[http-cors-allow-origin]]
8686
// tag::http-cors-allow-origin-tag[]
8787
`http.cors.allow-origin` {ess-icon}::
88-
(<<static-cluster-setting,Static>>)
88+
(<<static-cluster-setting,Static>>, string)
8989
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.
9090
+
9191
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*.
@@ -95,109 +95,115 @@ IMPORTANT: A wildcard (`*`) is a valid value but is considered a security risk,
9595
[[http-cors-max-age]]
9696
// tag::http-cors-max-age-tag[]
9797
`http.cors.max-age` {ess-icon}::
98-
(<<static-cluster-setting,Static>>)
99-
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).
98+
(<<static-cluster-setting,Static>>, integer)
99+
Browsers send a "preflight" OPTIONS-request to determine CORS settings.
100+
`max-age` defines for how long, in seconds, the result should be cached.
101+
Defaults to `1728000` (20 days).
100102
// end::http-cors-max-age-tag[]
101103

102104
[[http-cors-allow-methods]]
103105
// tag::http-cors-allow-methods-tag[]
104106
`http.cors.allow-methods` {ess-icon}::
105-
(<<static-cluster-setting,Static>>)
107+
(<<static-cluster-setting,Static>>, string)
106108
Which methods to allow. Defaults to `OPTIONS, HEAD, GET, POST, PUT, DELETE`.
107109
// end::http-cors-allow-methods-tag[]
108110

109111
[[http-cors-allow-headers]]
110112
// tag::http-cors-allow-headers-tag[]
111113
`http.cors.allow-headers` {ess-icon}::
112-
(<<static-cluster-setting,Static>>)
114+
(<<static-cluster-setting,Static>>, string)
113115
Which headers to allow. Defaults to `X-Requested-With, Content-Type, Content-Length`.
114116
// end::http-cors-allow-headers-tag[]
115117

116118
[[http-cors-allow-credentials]]
117119
// tag::http-cors-allow-credentials-tag[]
118120
`http.cors.allow-credentials` {ess-icon}::
119-
(<<static-cluster-setting,Static>>)
121+
(<<static-cluster-setting,Static>>, boolean)
120122
Whether the `Access-Control-Allow-Credentials` header should be returned. Defaults to `false`.
121123
+
122124
NOTE: This header is only returned when the setting is set to `true`.
123125

124126
// end::http-cors-allow-credentials-tag[]
125127

126128
`http.detailed_errors.enabled`::
127-
(<<static-cluster-setting,Static>>)
129+
(<<static-cluster-setting,Static>>, boolean)
128130
If `true`, enables the output of detailed error messages and stack traces in the response output. Defaults to `true`.
129131
+
130132
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.
131133

132134
`http.pipelining.max_events`::
133-
(<<static-cluster-setting,Static>>)
135+
(<<static-cluster-setting,Static>>, integer)
134136
The maximum number of events to be queued up in memory before an HTTP connection is closed, defaults to `10000`.
135137

136138
`http.max_warning_header_count`::
137-
(<<static-cluster-setting,Static>>)
138-
The maximum number of warning headers in client HTTP responses. Defaults to `unbounded`.
139+
(<<static-cluster-setting,Static>>, integer)
140+
The maximum number of warning headers in client HTTP responses. Defaults to
141+
`-1` which means the number of warning headers is unlimited.
139142

140143
`http.max_warning_header_size`::
141-
(<<static-cluster-setting,Static>>)
142-
The maximum total size of warning headers in client HTTP responses. Defaults to `unbounded`.
143-
144-
`http.tcp.no_delay`::
145-
(<<static-cluster-setting,Static>>)
146-
Enable or disable the {wikipedia}/Nagle%27s_algorithm[TCP no delay]
147-
setting. Defaults to `network.tcp.no_delay`.
144+
(<<static-cluster-setting,Static>>, <<byte-units,byte value>>)
145+
The maximum total size of warning headers in client HTTP responses. Defaults to
146+
`-1` which means the size of the warning headers is unlimited.
148147

149148
`http.tcp.keep_alive`::
150-
(<<static-cluster-setting,Static>>)
151-
Configures the `SO_KEEPALIVE` option for this socket, which
152-
determines whether it sends TCP keepalive probes.
153-
Defaults to `network.tcp.keep_alive`.
149+
(<<static-cluster-setting,Static>>, boolean)
150+
Configures the `SO_KEEPALIVE` option for this socket, which determines whether
151+
it sends TCP keepalive probes. Defaults to `network.tcp.keep_alive`.
154152

155153
`http.tcp.keep_idle`::
156-
(<<static-cluster-setting,Static>>) Configures the `TCP_KEEPIDLE` option for this socket, which
157-
determines the time in seconds that a connection must be idle before
158-
starting to send TCP keepalive probes. Defaults to `network.tcp.keep_idle`, which
159-
uses the system default. This value cannot exceed `300` seconds. Only applicable on
160-
Linux and macOS, and requires Java 11 or newer.
154+
(<<static-cluster-setting,Static>>, integer)
155+
Configures the `TCP_KEEPIDLE` option for HTTP sockets, which determines the
156+
time in seconds that a connection must be idle before starting to send TCP
157+
keepalive probes. Defaults to `network.tcp.keep_idle`, which uses the system
158+
default. This value cannot exceed `300` seconds. Only applicable on Linux and
159+
macOS.
161160

162161
`http.tcp.keep_interval`::
163-
(<<static-cluster-setting,Static>>) Configures the `TCP_KEEPINTVL` option for this socket,
164-
which determines the time in seconds between sending TCP keepalive probes.
165-
Defaults to `network.tcp.keep_interval`, which uses the system default.
166-
This value cannot exceed `300` seconds. Only applicable on Linux and macOS, and requires
167-
Java 11 or newer.
162+
(<<static-cluster-setting,Static>>, integer)
163+
Configures the `TCP_KEEPINTVL` option for HTTP sockets, which determines the
164+
time in seconds between sending TCP keepalive probes. Defaults to
165+
`network.tcp.keep_interval`, which uses the system default. This value cannot
166+
exceed `300` seconds. Only applicable on Linux and macOS.
168167

169168
`http.tcp.keep_count`::
170-
(<<static-cluster-setting,Static>>) Configures the `TCP_KEEPCNT` option for this socket, which
171-
determines the number of unacknowledged TCP keepalive probes that may be
172-
sent on a connection before it is dropped. Defaults to `network.tcp.keep_count`,
173-
which uses the system default. Only applicable on Linux and macOS, and
174-
requires Java 11 or newer.
169+
(<<static-cluster-setting,Static>>, integer)
170+
Configures the `TCP_KEEPCNT` option for HTTP sockets, which determines the
171+
number of unacknowledged TCP keepalive probes that may be sent on a connection
172+
before it is dropped. Defaults to `network.tcp.keep_count`, which uses the
173+
system default. Only applicable on Linux and macOS.
174+
175+
`http.tcp.no_delay`::
176+
(<<static-cluster-setting,Static>>, boolean)
177+
Configures the `TCP_NODELAY` option on HTTP sockets, which determines whether
178+
{wikipedia}/Nagle%27s_algorithm[TCP no delay] is enabled. Defaults to `true`.
175179

176180
`http.tcp.reuse_address`::
177-
(<<static-cluster-setting,Static>>)
178-
Should an address be reused or not. Defaults to `network.tcp.reuse_address`.
181+
(<<static-cluster-setting,Static>>, boolean)
182+
Configures the `SO_REUSEADDR` option for HTTP sockets, which determines whether
183+
the address can be reused or not. Defaults to `false` on Windows and `true`
184+
otherwise.
179185

180186
`http.tcp.send_buffer_size`::
181-
(<<static-cluster-setting,Static>>)
182-
The size of the TCP send buffer (specified with <<size-units,size units>>).
183-
Defaults to `network.tcp.send_buffer_size`.
187+
(<<static-cluster-setting,Static>>, <<byte-units,byte value>>)
188+
The size of the TCP send buffer for HTTP traffic. Defaults to
189+
`network.tcp.send_buffer_size`.
184190

185191
`http.tcp.receive_buffer_size`::
186-
(<<static-cluster-setting,Static>>)
187-
The size of the TCP receive buffer (specified with <<size-units,size units>>).
188-
Defaults to `network.tcp.receive_buffer_size`.
192+
(<<static-cluster-setting,Static>>, <<byte-units,byte value>>)
193+
The size of the TCP receive buffer for HTTP traffic. Defaults to
194+
`network.tcp.receive_buffer_size`.
189195

190196
`http.client_stats.enabled`::
191-
(<<dynamic-cluster-setting,Dynamic>>)
197+
(<<dynamic-cluster-setting,Dynamic>>, boolean)
192198
Enable or disable collection of HTTP client stats. Defaults to `true`.
193199

194200
`http.client_stats.closed_channels.max_count`::
195-
(<<static-cluster-setting,Static>>)
201+
(<<static-cluster-setting,Static>>, integer)
196202
When `http.client_stats.enabled` is `true`, sets the maximum number of closed
197203
HTTP channels for which {es} reports statistics. Defaults to `10000`.
198204

199205
`http.client_stats.closed_channels.max_age`::
200-
(<<static-cluster-setting,Static>>)
206+
(<<static-cluster-setting,Static>>, <<time-units,time value>>)
201207
When `http.client_stats.enabled` is `true`, sets the maximum length of time
202208
after closing a HTTP channel that {es} will report that channel's statistics.
203209
Defaults to `5m`.

docs/reference/modules/network.asciidoc

Lines changed: 39 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -38,23 +38,23 @@ proceeding.
3838
Most users will need to configure only the following network settings.
3939

4040
`network.host`::
41-
(<<static-cluster-setting,Static>>)
41+
(<<static-cluster-setting,Static>>, string)
4242
Sets the address of this node for both HTTP and transport traffic. The node
4343
will bind to this address and will also use it as its publish address. Accepts
4444
an IP address, a hostname, or a <<network-interface-values,special value>>.
4545
+
4646
Defaults to `_local_`.
4747

4848
`http.port`::
49-
(<<static-cluster-setting,Static>>)
49+
(<<static-cluster-setting,Static>>, integer)
5050
The port to bind for HTTP client communication. Accepts a single value or a
5151
range. If a range is specified, the node will bind to the first available port
5252
in the range.
5353
+
5454
Defaults to `9200-9300`.
5555

5656
`transport.port`::
57-
(<<static-cluster-setting,Static>>)
57+
(<<static-cluster-setting,Static>>, integer)
5858
The port to bind for communication between nodes. Accepts a single value or a
5959
range. If a range is specified, the node will bind to the first available port
6060
in the range. Set this setting to a single port, not a range, on every
@@ -170,15 +170,15 @@ you should not use them if you can use the <<common-network-settings,commonly
170170
used settings>> instead.
171171

172172
`network.bind_host`::
173-
(<<static-cluster-setting,Static>>)
173+
(<<static-cluster-setting,Static>>, string)
174174
The network address(es) to which the node should bind in order to listen for
175175
incoming connections. Accepts a list of IP addresses, hostnames, and
176176
<<network-interface-values,special values>>. Defaults to the address given by
177177
`network.host`. Use this setting only if binding to multiple addresses or using
178178
different addresses for publishing and binding.
179179

180180
`network.publish_host`::
181-
(<<static-cluster-setting,Static>>)
181+
(<<static-cluster-setting,Static>>, string)
182182
The network address that clients and other nodes can use to contact this node.
183183
Accepts an IP address, a hostname, or a <<network-interface-values,special
184184
value>>. Defaults to the address given by `network.host`. Use this setting only
@@ -199,53 +199,53 @@ each node is accessible at all possible publish addresses.
199199
Use the following settings to control the low-level parameters of the TCP
200200
connections used by the HTTP and transport interfaces.
201201

202-
`network.tcp.no_delay`::
203-
(<<static-cluster-setting,Static>>)
204-
Enable or disable the {wikipedia}/Nagle%27s_algorithm[TCP no delay]
205-
setting. Defaults to `true`.
206-
207202
`network.tcp.keep_alive`::
208-
(<<static-cluster-setting,Static>>)
209-
Configures the `SO_KEEPALIVE` option for this socket, which
210-
determines whether it sends TCP keepalive probes.
203+
(<<static-cluster-setting,Static>>, boolean)
204+
Configures the `SO_KEEPALIVE` option for network sockets, which determines
205+
whether each connection sends TCP keepalive probes. Defaults to `true`.
211206

212207
`network.tcp.keep_idle`::
213-
(<<static-cluster-setting,Static>>)
214-
Configures the `TCP_KEEPIDLE` option for this socket, which
215-
determines the time in seconds that a connection must be idle before
216-
starting to send TCP keepalive probes. Defaults to `-1`, which uses
217-
the system default. This value cannot exceed `300` seconds. Only applicable on Linux and macOS,
218-
and requires Java 11 or newer.
208+
(<<static-cluster-setting,Static>>, integer)
209+
Configures the `TCP_KEEPIDLE` option for network sockets, which determines the
210+
time in seconds that a connection must be idle before starting to send TCP
211+
keepalive probes. Defaults to `-1`, which means to use the system default. This
212+
value cannot exceed `300` seconds. Only applicable on Linux and macOS.
219213

220214
`network.tcp.keep_interval`::
221-
(<<static-cluster-setting,Static>>)
222-
Configures the `TCP_KEEPINTVL` option for this socket,
223-
which determines the time in seconds between sending TCP keepalive probes.
224-
Defaults to `-1`, which uses the system default. This value cannot exceed `300` seconds.
225-
Only applicable on Linux and macOS, and requires Java 11 or newer.
215+
(<<static-cluster-setting,Static>>, integer)
216+
Configures the `TCP_KEEPINTVL` option for network sockets, which determines the
217+
time in seconds between sending TCP keepalive probes. Defaults to `-1`, which
218+
means to use the system default. This value cannot exceed `300` seconds. Only
219+
applicable on Linux and macOS.
226220

227221
`network.tcp.keep_count`::
228-
(<<static-cluster-setting,Static>>)
229-
Configures the `TCP_KEEPCNT` option for this socket, which
230-
determines the number of unacknowledged TCP keepalive probes that may be
231-
sent on a connection before it is dropped. Defaults to `-1`,
232-
which uses the system default. Only applicable on Linux and macOS, and requires
233-
Java 11 or newer.
222+
(<<static-cluster-setting,Static>>, integer)
223+
Configures the `TCP_KEEPCNT` option for network sockets, which determines the
224+
number of unacknowledged TCP keepalive probes that may be sent on a connection
225+
before it is dropped. Defaults to `-1`, which means to use the system default.
226+
Only applicable on Linux and macOS.
227+
228+
`network.tcp.no_delay`::
229+
(<<static-cluster-setting,Static>>, boolean)
230+
Configures the `TCP_NODELAY` option on network sockets, which determines
231+
whether {wikipedia}/Nagle%27s_algorithm[TCP no delay] is enabled. Defaults to
232+
`true`.
234233

235234
`network.tcp.reuse_address`::
236-
(<<static-cluster-setting,Static>>)
237-
Should an address be reused or not. Defaults to `true` on non-windows
238-
machines.
235+
(<<static-cluster-setting,Static>>, boolean)
236+
Configures the `SO_REUSEADDR` option for network sockets, which determines
237+
whether the address can be reused or not. Defaults to `false` on Windows and
238+
`true` otherwise.
239239

240240
`network.tcp.send_buffer_size`::
241-
(<<static-cluster-setting,Static>>)
242-
The size of the TCP send buffer (specified with <<size-units,size units>>).
243-
By default not explicitly set.
241+
(<<static-cluster-setting,Static>>, <<byte-units,byte value>>)
242+
Configures the size of the TCP send buffer for network sockets. Defaults to
243+
`-1` which means to use the system default.
244244

245245
`network.tcp.receive_buffer_size`::
246-
(<<static-cluster-setting,Static>>)
247-
The size of the TCP receive buffer (specified with <<size-units,size units>>).
248-
By default not explicitly set.
246+
(<<static-cluster-setting,Static>>, <<byte-units,byte value>>)
247+
Configures the size of the TCP receive buffer. Defaults to `-1` which means to
248+
use the system default.
249249

250250
include::http.asciidoc[]
251251

0 commit comments

Comments
 (0)