11[[advanced-configuration]]
2- === Advanced configuration settings
2+ === Advanced configuration
33
4- The settings below are considered advanced and for expert users only. In
5- most cases the {es}-provided default settings should be used. Take caution
6- when modifying these settings as this could result in undesired behavior or
7- reduced system performance.
4+ Modifying advanced settings is generally not recommended and could negatively
5+ impact performance and stability. Using the {es}-provided defaults
6+ is recommended in most circumstances.
87
9- [[setting -jvm-heap-size ]]
10- ==== Setting JVM heap size
8+ [[set -jvm-options ]]
9+ ==== Set JVM options
1110
12- If you need to override the default <<heap-size-settings,heap size settings>>,
13- follow the best practices below .
11+ If needed, you can override the default JVM options by adding custom options
12+ files (preferred) or setting the `ES_JAVA_OPTS` environment variable .
1413
15- {es} assigns the entire heap specified in
16- <<jvm-options,jvm.options>> via the `Xms` (minimum heap size) and `Xmx` (maximum
17- heap size) settings. These two settings must be equal to each other.
14+ JVM options files must have the suffix '.options' and contain a line-delimited
15+ list of JVM arguments. JVM processes options files in lexicographic order.
1816
19- The value for these settings depends on the amount of RAM available on your
20- server:
17+ Where you put the JVM options files depends on the type of installation:
2118
22- * Set `Xmx` and `Xms` to no more than 50% of your total system memory. {es} requires
23- memory for purposes other than the JVM heap and it is important to leave
24- space for this. For instance, {es} uses off-heap buffers for efficient
25- network communication, relies on the operating system's filesystem cache for
26- efficient access to files, and the JVM itself requires some memory too. It is
27- normal to observe the {es} process using more memory than the limit
19+ * tar.gz or .zip: Add custom JVM options files to `config/jvm.options.d/`.
20+ * Debian or RPM: Add custom JVM options files to `/etc/elasticsearch/jvm.options.d/`.
21+ * Docker: Bind mount custom JVM options files into
22+ `/usr/share/elasticsearch/config/jvm.options.d/`.
23+
24+ NOTE: Do not modify the root `jvm.options` file. Use JVM options files instead.
25+
26+ [[jvm-options-syntax]]
27+ ===== JVM options syntax
28+
29+ A JVM options file contains a line-delimited list of JVM arguments.
30+ Arguments are preceded by a dash (`-`).
31+ To apply the setting to specific versions, prepend the version
32+ or a range of versions followed by a colon.
33+
34+ * Apply a setting to all versions:
35+ +
36+ [source,text]
37+ -------------------------------------
38+ -Xmx2g
39+ -------------------------------------
40+
41+ * Apply a setting to a specific version:
42+ +
43+ [source,text]
44+ -------------------------------------
45+ 8:-Xmx2g
46+ -------------------------------------
47+
48+ * Apply a setting to a range of versions:
49+ +
50+ [source,text]
51+ -------------------------------------
52+ 8-9:-Xmx2g
53+ -------------------------------------
54+ +
55+ To apply a setting to a specific version and any later versions,
56+ omit the upper bound of the range.
57+ For example, this setting applies to Java 8 and later:
58+ +
59+ [source,text]
60+ -------------------------------------
61+ 8-:-Xmx2g
62+ -------------------------------------
63+
64+ Blank lines are ignored. Lines beginning with `#` are treated as comments
65+ and ignored. Lines that aren't commented out and aren't recognized
66+ as valid JVM arguments are rejected and {es} will fail to start.
67+
68+ [[jvm-options-env]]
69+ ===== Use environment variables to set JVM options
70+
71+ In production, use JVM options files to override the
72+ default settings. In testing and development environments,
73+ you can also set JVM options through the `ES_JAVA_OPTS` environment variable.
74+
75+ [source,sh]
76+ ---------------------------------
77+ export ES_JAVA_OPTS="$ES_JAVA_OPTS -Djava.io.tmpdir=/path/to/temp/dir"
78+ ./bin/elasticsearch
79+ ---------------------------------
80+
81+ If you're using the RPM or Debian packages, you can specify
82+ `ES_JAVA_OPTS` in the <<sysconfig,system configuration file>>.
83+
84+ NOTE: {es} ignores the `JAVA_TOOL_OPTIONS` and `JAVA_OPTS` environment variables.
85+
86+ [[set-jvm-heap-size]]
87+ ==== Set the JVM heap size
88+
89+ By default, {es} automatically sets the JVM heap size based on a node's
90+ <<node-roles,roles>> and total memory.
91+ Using the default sizing is recommended for most production environments.
92+
93+ NOTE: Automatic heap sizing requires the <<jvm-version,bundled JDK>> or, if using
94+ a custom JRE location, a Java 14 or later JRE.
95+
96+ To override the default heap size, set the minimum and maximum heap size
97+ settings, `Xms` and `Xmx`. The minimum and maximum values must be the same.
98+
99+ The heap size should be based on the available RAM:
100+
101+ * Set `Xms` and `Xmx` to no more than 50% of your total memory. {es} requires
102+ memory for purposes other than the JVM heap. For example, {es} uses
103+ off-heap buffers for efficient network communication and relies
104+ on the operating system's filesystem cache for
105+ efficient access to files. The JVM itself also requires some memory. It's
106+ normal for {es} to use more memory than the limit
28107configured with the `Xmx` setting.
108+ +
109+ NOTE: When running in a container, such as <<docker,Docker>>, total memory is
110+ defined as the amount of memory visible to the container, not the total system
111+ memory on the host.
29112
30- * Set `Xmx ` and `Xms ` to no more than the threshold that the JVM uses for
31- compressed object pointers (compressed oops). The exact threshold varies but
32- is near 32 GB. You can verify that you are under the threshold by looking for a line in the logs like the following :
113+ * Set `Xms ` and `Xmx ` to no more than 32 GB, the approximate threshold for
114+ compressed ordinary object pointers (oops). To verify you are under the
115+ threshold, check `elasticsearch.logs` for an entry like this :
33116+
34117[source,txt]
35118----
36119heap size [1.9gb], compressed ordinary object pointers [true]
37120----
38121
39- * Set `Xmx ` and `Xms ` to no more than the threshold for zero-based
122+ * Set `Xms ` and `Xmx ` to no more than the threshold for zero-based
40123compressed oops. The exact threshold varies but 26GB is safe on most
41124systems and can be as large as 30GB on some systems. You can verify that
42125you are under this threshold by starting {es} with the JVM options
43- `-XX:+UnlockDiagnosticVMOptions -XX:+PrintCompressedOopsMode` and looking for
44- a line like the following :
126+ `-XX:+UnlockDiagnosticVMOptions -XX:+PrintCompressedOopsMode` and checking
127+ `elasticsearch.logs` for an entry like this :
45128+
46129[source,txt]
47130----
48131heap address: 0x000000011be00000, size: 27648 MB, zero based Compressed Oops
49132----
50133+
51- This line shows that zero-based compressed oops are enabled. If zero-based
52- compressed oops are not enabled, you'll see a line like the following instead :
134+ This entry shows that zero-based compressed oops are enabled. If zero-based
135+ compressed oops are not enabled, the entry looks like this :
53136+
54137[source,txt]
55138----
@@ -61,31 +144,27 @@ caches. This leaves less memory for the operating system to use
61144for the filesystem cache. Larger heaps can also cause longer garbage
62145collection pauses.
63146
64- Here is an example of how to set the heap size via a `jvm.options.d/` file:
147+ To configure the heap size, add the `Xms` and `Xmx` JVM arguments to a
148+ custom JVM options file with the extension `.options` and
149+ store it in the `jvm.options.d/` directory.
150+ For example, to set the maximum heap size to 2GB, set both `Xms` and `Xmx` to `2g`:
65151
66152[source,txt]
67153------------------
68- -Xms2g <1>
69- -Xmx2g <2>
154+ -Xms2g
155+ -Xmx2g
70156------------------
71- <1> Set the minimum heap size to 2g.
72- <2> Set the maximum heap size to 2g.
73-
74- In production, we recommend using `jvm.options.d` to configure heap sizes.
75157
76158For testing, you can also set the heap sizes using the `ES_JAVA_OPTS`
77- environment variable. The `ES_JAVA_OPTS` variable overrides all other JVM
78- options. We do not recommend using `ES_JAVA_OPTS` in production.
159+ environment variable:
79160
80161[source,sh]
81162------------------
82- ES_JAVA_OPTS="-Xms2g -Xmx2g" ./bin/elasticsearch <1>
83- ES_JAVA_OPTS="-Xms4000m -Xmx4000m" ./bin/elasticsearch <2>
163+ ES_JAVA_OPTS="-Xms2g -Xmx2g" ./bin/elasticsearch
84164------------------
85- <1> Set the minimum and maximum heap size to 2 GB.
86- <2> Set the minimum and maximum heap size to 4000 MB.
87165
88- NOTE: Configuring the heap for the <<windows-service,Windows service>> is
89- different than the above. The values initially populated for the Windows
90- service can be configured as above but are different after the service has been
91- installed. See <<windows-service>>.
166+ The `ES_JAVA_OPTS` variable overrides all other JVM
167+ options. We do not recommend using `ES_JAVA_OPTS` in production.
168+
169+ NOTE: If you are running {es} as a Windows service, you can change the heap size
170+ using the service manager. See <<windows-service>>.
0 commit comments