honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
OpenSearch/docs/reference/setup/sysconfig/configuring.asciidoc

150 lines
5.0 KiB
Plaintext
Raw Normal View History

Docs: Complete rewrite of setup, installation, and configuration docs
2016-04-03 10:09:24 -04:00
[[setting-system-settings]]
=== Configuring system settings
Where to configure systems settings depends on which package you have used to
install Elasticsearch, and which operating system you are using.
When using the `.zip` or `.tar.gz` packages, system settings can be configured:
* temporarily with <<ulimit,`ulimit`>>, or
* permanently in <<limits.conf,`/etc/security/limits.conf`>>.
When using the RPM or Debian packages, most system settings are set in the
<<sysconfig,system configuration file>>. However, systems which use systemd
require that system limits are specified in a
<<systemd,systemd configuration file>>.
[[ulimit]]
==== `ulimit`
On Linux systems, `ulimit` can be used to change resource limits on a
temporary basis. Limits usually need to be set as `root` before switching to
the user that will run Elasticsearch. For example, to set the number of
open file handles (`ulimit -n`) to 65,536, you can do the following:
[source,sh]
--------------------------------
sudo su <1>
ulimit -n 65536 <2>
su elasticsearch <3>
--------------------------------
<1> Become `root`.
<2> Change the max number of open files.
<3> Become the `elasticsearch` user in order to start Elasticsearch.
The new limit is only applied during the current session.
You can consult all currently applied limits with `ulimit -a`.
[[limits.conf]]
==== `/etc/security/limits.conf`
On Linux systems, persistent limits can be set for a particular user by
editing the `/etc/security/limits.conf` file. To set the maximum number of
open files for the `elasticsearch` user to 65,536, add the following line to
the `limits.conf` file:
[source,sh]
--------------------------------
elasticsearch - nofile 65536
--------------------------------
This change will only take effect the next time the `elasticsearch` user opens
a new session.
[NOTE]
.Ubuntu and `limits.conf`
===============================
Ubuntu ignores the `limits.conf` file for processes started by `init.d`. To
enable the `limits.conf` file, edit `/etc/pam.d/su` and uncomment the
following line:
[source,sh]
--------------------------------
# session required pam_limits.so
--------------------------------
===============================
[[sysconfig]]
==== Sysconfig file
When using the RPM or Debian packages, system settings and environment
variables can be specified in the system configuration file, which is located
in:
[horizontal]
RPM:: `/etc/sysconfig/elasticsearch`
Debian:: `/etc/default/elasticsearch`
However, for systems which uses `systemd`, system limits need to be specified
via <<systemd,systemd>>.
[[systemd]]
==== Systemd configuration
When using the RPM or Debian packages on systems that use
https://en.wikipedia.org/wiki/Systemd[systemd], system limits must be
specified via systemd.
The systemd service file (`/usr/lib/systemd/system/elasticsearch.service`)
contains the limits that are applied by default.
Clarify systemd overrides This commit clarifies how to apply an override to the systemd unit file for Elasticsearch. Relates #26950
2017-10-10 13:06:34 -04:00
To override them, add a file called
`/etc/systemd/system/elasticsearch.service.d/override.conf` (alternatively,
you may run `sudo systemctl edit elasticsearch` which opens the file
automatically inside your default editor). Set any changes in this file,
such as:
Docs: Complete rewrite of setup, installation, and configuration docs
2016-04-03 10:09:24 -04:00
[source,sh]
---------------------------------
Fix systemd override example in configuring docs When overriding a systemd configuration via a drop-in file, the [Service] header is required. This commit adds this to an example drop-in override in the configuring docs. Relates #22038
2016-12-07 19:41:59 -05:00
[Service]
Docs: Complete rewrite of setup, installation, and configuration docs
2016-04-03 10:09:24 -04:00
LimitMEMLOCK=infinity
---------------------------------
Clarify systemd overrides This commit clarifies how to apply an override to the systemd unit file for Elasticsearch. Relates #26950
2017-10-10 13:06:34 -04:00
Once finished, run the following command to reload units:
[source,sh]
---------------------------------
sudo systemctl daemon-reload
---------------------------------
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
2016-12-01 17:26:29 -05:00
[[jvm-options]]
==== Setting JVM options
Docs: Complete rewrite of setup, installation, and configuration docs
2016-04-03 10:09:24 -04:00
Add JVM options configuration file This commit adds a new configuration file jvm.options to centralize and simplify management of JVM options. This separates the configuration of the JVM from the packaging scripts (bin/elasticsearch*, bin/service.bat, and init.d/elasticsearch) simplifying end-user operational management of custom JVM options.
2016-04-11 07:15:19 -04:00
The preferred method of setting Java Virtual Machine options (including
Update configuring.asciidoc Minor asciidoc changes
2016-05-29 05:50:36 -04:00
system properties and JVM flags) is via the `jvm.options` configuration
file. The default location of this file is `config/jvm.options` (when
Add JVM options configuration file This commit adds a new configuration file jvm.options to centralize and simplify management of JVM options. This separates the configuration of the JVM from the packaging scripts (bin/elasticsearch*, bin/service.bat, and init.d/elasticsearch) simplifying end-user operational management of custom JVM options.
2016-04-11 07:15:19 -04:00
installing from the tar or zip distributions) and
Update configuring.asciidoc Minor asciidoc changes
2016-05-29 05:50:36 -04:00
`/etc/elasticsearch/jvm.options` (when installing from the Debian or RPM
Add JVM options configuration file This commit adds a new configuration file jvm.options to centralize and simplify management of JVM options. This separates the configuration of the JVM from the packaging scripts (bin/elasticsearch*, bin/service.bat, and init.d/elasticsearch) simplifying end-user operational management of custom JVM options.
2016-04-11 07:15:19 -04:00
packages). This file contains a line-delimited list of JVM arguments,
which must begin with `-`. You can add custom JVM flags to this file and
check this configuration into your version control system.
An alternative mechanism for setting Java Virtual Machine options is
via the `ES_JAVA_OPTS` environment variable. For instance:
Docs: Complete rewrite of setup, installation, and configuration docs
2016-04-03 10:09:24 -04:00
[source,sh]
---------------------------------
Add JVM options configuration file This commit adds a new configuration file jvm.options to centralize and simplify management of JVM options. This separates the configuration of the JVM from the packaging scripts (bin/elasticsearch*, bin/service.bat, and init.d/elasticsearch) simplifying end-user operational management of custom JVM options.
2016-04-11 07:15:19 -04:00
export ES_JAVA_OPTS="$ES_JAVA_OPTS -Djava.io.tmpdir=/path/to/temp/dir"
Docs: Complete rewrite of setup, installation, and configuration docs
2016-04-03 10:09:24 -04:00
./bin/elasticsearch
---------------------------------
Add JVM options configuration file This commit adds a new configuration file jvm.options to centralize and simplify management of JVM options. This separates the configuration of the JVM from the packaging scripts (bin/elasticsearch*, bin/service.bat, and init.d/elasticsearch) simplifying end-user operational management of custom JVM options.
2016-04-11 07:15:19 -04:00
When using the RPM or Debian packages, `ES_JAVA_OPTS` can be specified in the
Docs: Complete rewrite of setup, installation, and configuration docs
2016-04-03 10:09:24 -04:00
<<sysconfig,system configuration file>>.
Also skip JAVA_TOOL_OPTIONS on Windows On non-Windows platforms, we ignore the environment variable JAVA_TOOL_OPTIONS (this is an environment variable that the JVM respects by default for picking up extra JVM options). The primary reason that we ignore this because of the Jayatana agent on Ubuntu; a secondary reason is that it produces an annoying "Picked up JAVA_TOOL_OPTIONS: ..." output message. When the elasticsearch-env batch script was introduced for Windows, ignoring this environment variable was deliberately not carried over as the primary reason does not apply on Windows. However, after additional thinking, it seems that we should simply be consistent to the extent possible here (and also avoid that annoying "Picked up JAVA_TOOL_OPTIONS: ..." on Windows too). This commit causes the Windows version of elasticsearch-env to also ignore JAVA_TOOL_OPTIONS. Relates #25968
2017-07-31 08:27:42 -04:00
The JVM has a built-in mechanism for observing the `JAVA_TOOL_OPTIONS`
environment variable. We intentionally ignore this environment variable in our
packaging scripts. The primary reason for this is that on some OS (e.g., Ubuntu)
there are agents installed by default via this environment variable that we do
not want interfering with Elasticsearch.
Additionally, some other Java programs support the `JAVA_OPTS` environment
variable. This is *not* a mechanism built into the JVM but instead a convention
in the ecosystem. However, we do not support this environment variable, instead
supporting setting JVM options via the `jvm.options` file or the environment
variable `ES_JAVA_OPTS` as above.