From b9df2e228714ad36081298f1b168cce02ff3ee1e Mon Sep 17 00:00:00 2001 From: Jason Tedor Date: Thu, 1 Dec 2016 17:26:29 -0500 Subject: [PATCH] Improve the out-of-the-box experience Elasticsearch can be run in a few different ways: - from the command line on Linux and Windows - as a service on Linux and Windows on both 32-bit client and 64-bit server VMs. We strive for a great out-of-the-box experience any of these combinations but today it is lacking on 32-bit client JVMs and on the Windows service. There are two deficiencies that arise: - on any 32-bit client JVM we fail to start out of the box because we force the server JVM in jvm.options - when installing the Windows service, the thread stack size must be specified in jvm.options This commit attempts to address these deficiencies. We should continue to force the server JVM because there are systems where the server JVM is not active by default (e.g., the 32-bit JDK on Windows). This does mean that if a user tries to run with a client JVM they will see a failure message at startup but this is the best that we can do if we want to continue to force the server JVM. Thus, this commit at least documents this situation. To improve the situation with installing the Windows service, this commit adds a default setting for the thread stack size. This default is chosen based on the default thread stack size across all 64-bit server JVMs. This means that if a user tries to run with a 32-bit JVM they could otherwise see significantly higher memory usage (this situation is complicated, it's really only on Windows where the extra memory usage is egregious, but cutting into the 32-bit address space on any system is bad). So this commit makes it so that the out-of-the-box experience is improved for the Windows service on 64-bit server JVMs and we document the need to adjust this setting on 32-bit JVMs. Again, we are focusing on the out-of-the-box experience here and this means optimizing for the best experience on any 64-bit server JVM as this covers the vast majority of the user base. The users that are on 32-bit JVMs will suffer a little bit but at least now any user on any 64-bit server JVM can start Elasticsearch out of the box. Finally, we fix some references to the jvm.options documentation. Relates #21920 --- distribution/src/main/resources/config/jvm.options | 5 ++++- docs/reference/modules/scripting/security.asciidoc | 2 +- docs/reference/setup.asciidoc | 4 ++++ docs/reference/setup/install/windows.asciidoc | 5 ----- docs/reference/setup/sysconfig/configuring.asciidoc | 4 ++-- docs/reference/setup/sysconfig/heap_size.asciidoc | 2 +- 6 files changed, 12 insertions(+), 10 deletions(-) diff --git a/distribution/src/main/resources/config/jvm.options b/distribution/src/main/resources/config/jvm.options index 37c4d5b3c93..11ec1cd66dc 100644 --- a/distribution/src/main/resources/config/jvm.options +++ b/distribution/src/main/resources/config/jvm.options @@ -47,9 +47,12 @@ ## basic -# force the server VM +# force the server VM (remove on 32-bit client JVMs) -server +# explicitly set the stack size (reduce to 320k on 32-bit client JVMs) +-Xss1m + # set to headless, just in case -Djava.awt.headless=true diff --git a/docs/reference/modules/scripting/security.asciidoc b/docs/reference/modules/scripting/security.asciidoc index 072b954b72f..3b40937c2d8 100644 --- a/docs/reference/modules/scripting/security.asciidoc +++ b/docs/reference/modules/scripting/security.asciidoc @@ -218,7 +218,7 @@ Security Policy either: * system wide: `$JAVA_HOME/lib/security/java.policy`, * for just the `elasticsearch` user: `/home/elasticsearch/.java.policy` -* by adding a system property to the <> configuration: `-Djava.security.policy=someURL`, or +* by adding a system property to the <> configuration: `-Djava.security.policy=someURL`, or * via the `ES_JAVA_OPTS` environment variable with `-Djava.security.policy=someURL`: + [source,js] diff --git a/docs/reference/setup.asciidoc b/docs/reference/setup.asciidoc index ae3c5b3beb4..2608f461dba 100644 --- a/docs/reference/setup.asciidoc +++ b/docs/reference/setup.asciidoc @@ -34,6 +34,10 @@ refuse to start if a known-bad version of Java is used. The version of Java that Elasticsearch will use can be configured by setting the `JAVA_HOME` environment variable. +NOTE: Elasticsearch ships with default configuration for running Elasticsearch on 64-bit server JVMs. If you are using a 32-bit client JVM, +you must remove `-server` from <> and if you are using any 32-bit JVM you should reconfigure the thread stack size +from `-Xss1m` to `-Xss320k`. + -- include::setup/install.asciidoc[] diff --git a/docs/reference/setup/install/windows.asciidoc b/docs/reference/setup/install/windows.asciidoc index d33558b913f..37d06e18d68 100644 --- a/docs/reference/setup/install/windows.asciidoc +++ b/docs/reference/setup/install/windows.asciidoc @@ -119,11 +119,6 @@ Using JAVA_HOME (64-bit): "c:\jvm\jdk1.8" The service 'elasticsearch-service-x64' has been installed. -------------------------------------------------- -NOTE: The service installer requires that the thread stack size setting -be configured in jvm.options *before* you install the service. On -32-bit Windows, you should add `-Xss320k` to the jvm.options file, and -on 64-bit Windows you should add `-Xss1m` to the jvm.options file. - NOTE: While a JRE can be used for the Elasticsearch service, due to its use of a client VM (as opposed to a server JVM which offers better performance for long-running applications) its usage is discouraged and a warning will be issued. NOTE: Upgrading (or downgrading) JVM versions does not require the service to be reinstalled. However, upgrading across JVM types (e.g. JRE versus SE) is not supported, and does require the service to be reinstalled. diff --git a/docs/reference/setup/sysconfig/configuring.asciidoc b/docs/reference/setup/sysconfig/configuring.asciidoc index d022b4e4c9e..72f915cff61 100644 --- a/docs/reference/setup/sysconfig/configuring.asciidoc +++ b/docs/reference/setup/sysconfig/configuring.asciidoc @@ -101,8 +101,8 @@ any changes in that file, such as: LimitMEMLOCK=infinity --------------------------------- -[[es-java-opts]] -==== Setting JVM system properties +[[jvm-options]] +==== Setting JVM options The preferred method of setting Java Virtual Machine options (including system properties and JVM flags) is via the `jvm.options` configuration diff --git a/docs/reference/setup/sysconfig/heap_size.asciidoc b/docs/reference/setup/sysconfig/heap_size.asciidoc index 55fb95bc7e6..30023618f3f 100644 --- a/docs/reference/setup/sysconfig/heap_size.asciidoc +++ b/docs/reference/setup/sysconfig/heap_size.asciidoc @@ -6,7 +6,7 @@ and maximum size of 2 GB. When moving to production, it is important to configure heap size to ensure that Elasticsearch has enough heap available. -Elasticsearch will assign the entire heap specified in <> +Elasticsearch will assign the entire heap specified in <> via the Xms (minimum heap size) and Xmx (maximum heap size) settings. The value for these setting depends on the amount of RAM available on