Refocus the System settings page as configuration methods

deploy-manage/deploy/self-managed/bootstrap-checks.md

@@ -62,18 +62,17 @@
 
 $$$bootstrap-checks-file-descriptor$$$
 
 File descriptors are a Unix construct for tracking open "files". In Unix though, [everything is a file](https://en.wikipedia.org/wiki/Everything_is_a_file). For example, "files" could be a physical file, a virtual file (e.g., `/proc/loadavg`), or network sockets. {{es}} requires lots of file descriptors (e.g., every shard is composed of multiple segments and other files, plus connections to other nodes, etc.). This bootstrap check is enforced on OS X and Linux.
 
-To pass the file descriptor check, you might have to configure [file descriptors](file-descriptors.md).
+To pass the file descriptor check, you might have to configure [file descriptors](/deploy-manage/deploy/self-managed/file-descriptors.md). For how to apply limits on the host, refer to [System settings configuration methods](/deploy-manage/deploy/self-managed/setting-system-settings.md).
 :::
 
 :::{dropdown} Memory lock check
 
 $$$bootstrap-checks-memory-lock$$$
 
-When the JVM does a major garbage collection it touches every page of the heap. If any of those pages are swapped out to disk they will have to be swapped back in to memory. That causes lots of disk thrashing that {{es}} would much rather use to service requests. There are several ways to configure a system to disallow swapping. One way is by requesting the JVM to lock the heap in memory through `mlockall` (Unix) or virtual lock (Windows). This is done via the {{es}} setting [`bootstrap.memory_lock`](setup-configuration-memory.md#bootstrap-memory_lock). However, there are cases where this setting can be passed to {{es}} but {{es}} is not able to lock the heap (e.g., if the `elasticsearch` user does not have `memlock unlimited`). The memory lock check verifies that **if** the `bootstrap.memory_lock` setting is enabled, that the JVM was successfully able to lock the heap.
+When the JVM does a major garbage collection it touches every page of the heap. If any of those pages are swapped out to disk they will have to be swapped back in to memory. That causes lots of disk thrashing that {{es}} would much rather use to service requests. There are several ways to configure a system to disallow swapping. One way is by requesting the JVM to lock the heap in memory through `mlockall` (Unix) or virtual lock (Windows). This is done via the {{es}} setting [`bootstrap.memory_lock`](/deploy-manage/deploy/self-managed/setup-configuration-memory.md#bootstrap-memory_lock). However, there are cases where this setting can be passed to {{es}} but {{es}} is not able to lock the heap (e.g., if the `elasticsearch` user does not have `memlock unlimited`). The memory lock check verifies that **if** the `bootstrap.memory_lock` setting is enabled, that the JVM was successfully able to lock the heap.
 
-To pass the memory lock check, you might have to configure [`bootstrap.memory_lock`](setup-configuration-memory.md#bootstrap-memory_lock).
 :::
 
 :::{dropdown} Maximum number of threads check
@@ -82,7 +81,7 @@
 
 {{es}} executes requests by breaking the request down into stages and handing those stages off to different thread pool executors. There are different [thread pool executors](elasticsearch://reference/elasticsearch/configuration-reference/thread-pool-settings.md) for a variety of tasks within {{es}}. Thus, {{es}} needs the ability to create a lot of threads. The maximum number of threads check ensures that the {{es}} process has the rights to create enough threads under normal use. This check is enforced only on Linux.
 
-If you are on Linux, to pass the maximum number of threads check, you must configure your system to allow the {{es}} process the ability to create at least 4096 threads. This can be done via `/etc/security/limits.conf` using the `nproc` setting (note that you might have to increase the limits for the `root` user too).
+If you are on Linux, to pass the maximum number of threads check, you must configure your system to allow the {{es}} process the ability to create at least 4096 threads. This can be done via `/etc/security/limits.conf` using the `nproc` setting (note that you might have to increase the limits for the `root` user too). For how to apply limits, refer to [System settings configuration methods](/deploy-manage/deploy/self-managed/setting-system-settings.md).
 :::
 
 :::{dropdown} Max file size check

deploy-manage/deploy/self-managed/elasticsearch-service-user.md

@@ -42,7 +42,7 @@ This section applies to Linux and MacOS only. On Windows, the JVM manages most o
 
 {{es}} requires several kernel-level resource limits, such as open file descriptors, max threads, and memory lock, to be raised above their defaults. The kernel enforces these limits per process based on the user that spawned it, so they must be configured for the `elasticsearch` user. The [important system configuration](/deploy-manage/deploy/self-managed/important-system-configuration.md) section covers each limit and its required value.
 
-For instructions on applying these limits using `ulimit`, `/etc/security/limits.conf`, or `systemd`, refer to [Configure system settings](/deploy-manage/deploy/self-managed/setting-system-settings.md).
+For instructions on applying these limits using `ulimit`, `/etc/security/limits.conf`, or `systemd`, refer to [](/deploy-manage/deploy/self-managed/setting-system-settings.md).
 
 ## File and directory ownership and permissions
 

deploy-manage/deploy/self-managed/executable-jna-tmpdir.md

@@ -17,9 +17,9 @@
 
 {{es}} uses the Java Native Access (JNA) library, and another library called `libffi`, for executing some platform-dependent native code. On Linux, the native code backing these libraries is extracted at runtime into a temporary directory and then mapped into executable pages in {{es}}'s address space. This requires the underlying files not to be on a filesystem mounted with the `noexec` option.
 
 By default, {{es}} will create its temporary directory within `/tmp`. However, some hardened Linux installations mount `/tmp` with the `noexec` option by default. This prevents JNA and `libffi` from working correctly. For instance, at startup JNA may fail to load with an `java.lang.UnsatisfiedLinkerError` exception or with a message that says something similar to `failed to map segment from shared object`, or `libffi` may report a message such as `failed to allocate closure`. Note that the exception messages can differ between JVM versions. Additionally, the components of {{es}} that rely on execution of native code via JNA may fail with messages indicating that it is `because JNA is not available`.
 
-To resolve these problems, either remove the `noexec` option from your `/tmp` filesystem, or configure {{es}} to use a different location for its temporary directory by setting the [`$ES_TMPDIR`](/deploy-manage/deploy/self-managed/important-settings-configuration.md#es-tmpdir) environment variable. For instance:
+To resolve these problems, either remove the `noexec` option from your `/tmp` filesystem, or configure {{es}} to use a different location for its temporary directory by setting the [`$ES_TMPDIR`](/deploy-manage/deploy/self-managed/important-settings-configuration.md#es-tmpdir) environment variable. For example:
 
 * If you are running {{es}} directly from a shell, set `$ES_TMPDIR` as follows:
 

deploy-manage/deploy/self-managed/file-descriptors.md

@@ -15,11 +15,11 @@
 ::::
 
 
 {{es}} uses a lot of file descriptors or file handles. Running out of file descriptors can be disastrous and will most probably lead to data loss. Make sure to increase the limit on the number of open files descriptors for the user running {{es}} to 65,535 or higher.
 
-For the `.zip` and `.tar.gz` packages, set [`ulimit -n 65535`](setting-system-settings.md#ulimit) as root before starting {{es}},   or set `nofile` to `65535` in [`/etc/security/limits.conf`](setting-system-settings.md#limits.conf).
+Apply this limit using the [system settings configuration methods](setting-system-settings.md) for your install type. For example using `ulimit` and editing `/etc/security/limits.conf` for `.tar.gz` archives, or through `systemd` overrides when you need to change defaults on package-based installations.
 
 On macOS, you must also pass the JVM option `-XX:-MaxFDLimit` to {{es}} in order for it to make use of the higher file descriptor limit.
 
 RPM and Debian packages already default the maximum number of file descriptors to 65535 and do not require further configuration.
 
@@ -28,4 +28,3 @@
 ```console
 GET _nodes/stats/process?filter_path=**.max_file_descriptors
 ```
-

deploy-manage/deploy/self-managed/important-system-configuration.md

@@ -14,14 +14,14 @@
 
 The following settings **must** be considered before going to production:
 
-* [](elasticsearch-service-user.md)
-* [](setting-system-settings.md)
-* [](setup-configuration-memory.md)
-* [](vm-max-map-count.md)
-* [](max-number-of-threads.md)
-* [](file-descriptors.md) (Linux and MacOS only)
-* [](executable-jna-tmpdir.md) (Linux only)
-* [](system-config-tcpretries.md) (Linux only)
+* [](/deploy-manage/deploy/self-managed/elasticsearch-service-user.md): Run as a dedicated unprivileged user, keep numeric UID and GID consistent across nodes, and set correct ownership on config and data paths.
+* [](/deploy-manage/deploy/self-managed/setting-system-settings.md): Where and how to apply operating-system limits and environment variables for your install type.
+* [](/deploy-manage/deploy/self-managed/setup-configuration-memory.md): Avoid heap or process memory being swapped out; options include disabling swap, lowering swappiness, and `bootstrap.memory_lock`.
+* [](/deploy-manage/deploy/self-managed/vm-max-map-count.md): Set `vm.max_map_count` high enough for mmap-based index storage (for example `1048576` when required).
+* [](/deploy-manage/deploy/self-managed/max-number-of-threads.md): Allow the {{es}} user to create at least `4096` threads on Linux when you manage limits yourself.
+* [](/deploy-manage/deploy/self-managed/file-descriptors.md): Raise open file handles to at least `65,535` (Linux and macOS only).
+* [](/deploy-manage/deploy/self-managed/executable-jna-tmpdir.md): Ensure JNA and native libraries can execute from a temp path that is not mounted `noexec` (Linux only).
+* [](/deploy-manage/deploy/self-managed/system-config-tcpretries.md): Lower `net.ipv4.tcp_retries2` so node and network failures are detected sooner than the Linux default (Linux only).
 
 :::{tip}
 For examples of applying the relevant settings in a Docker environment, refer to [](/deploy-manage/deploy/self-managed/install-elasticsearch-docker-prod.md).

deploy-manage/deploy/self-managed/install-elasticsearch-docker-prod.md

@@ -131,7 +131,7 @@ You can also run an {{es}} container using both a custom UID and GID. You must e
 
 ## Increase ulimits for nofile and nproc [_increase_ulimits_for_nofile_and_nproc]
 
-Increased ulimits for [nofile](setting-system-settings.md) and [nproc](/deploy-manage/deploy/self-managed/bootstrap-checks.md#max-number-threads-check) must be available for the {{es}} containers. Verify the [init system](https://github.com/moby/moby/tree/ea4d1243953e6b652082305a9c3cda8656edab26/contrib/init) for the Docker daemon sets them to acceptable values.
+Increased ulimits for [open files](/deploy-manage/deploy/self-managed/file-descriptors.md) and [user process limits](/deploy-manage/deploy/self-managed/max-number-of-threads.md) must be available for the {{es}} containers. Verify the [init system](https://github.com/moby/moby/tree/ea4d1243953e6b652082305a9c3cda8656edab26/contrib/init) for the Docker daemon sets them to acceptable values.
 
 To check the Docker daemon defaults for ulimits, run:
 

deploy-manage/deploy/self-managed/max-number-of-threads.md

@@ -11,9 +11,10 @@ products:
 
 # Increase the maximum number of threads [max-number-of-threads]
 
-{{es}} uses a number of thread pools for different types of operations. It is important that it is able to create new threads whenever needed. Make sure that the number of threads that the {{es}} user can create is at least 4096.
+{{es}} uses a number of thread pools for different types of operations. It is important that it is able to create new threads whenever needed. Make sure that the number of threads that the {{es}} user can create is at least `4096`.
 
-This can be done by setting [`ulimit -u 4096`](setting-system-settings.md#ulimit) as root before starting {{es}}, or by setting `nproc` to `4096` in [`/etc/security/limits.conf`](setting-system-settings.md#limits.conf).
+To apply this limit, use the [system settings configuration methods](setting-system-settings.md) for your install type. For example, using `ulimit` and editing `/etc/security/limits.conf` for `.tar.gz` archives, or through `systemd` overrides when you need to change defaults on package-based installations.
 
 The package distributions when run as services under `systemd` will configure the number of threads for the {{es}} process automatically. No additional configuration is required.
 
+

deploy-manage/deploy/self-managed/setting-system-settings.md

@@ -1,4 +1,5 @@
 ---
+navigation_title: Configuration methods
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/setting-system-settings.html
 applies_to:
@@ -8,11 +9,17 @@
   - id: elasticsearch
 ---
 
-# Configure system settings [setting-system-settings]
+# System settings configuration methods [setting-system-settings]
 
-Where to configure systems settings depends on which package you have used to install {{es}}, and which operating system you are using.
+This page describes **where and how** to apply operating system limits and environment variables for {{es}}, depending on your installation package and `init` system.
 
-When using the `.zip` or `.tar.gz` packages, system settings can be configured:
+For **which** limits and values you must set (such as file descriptors, threads, memory lock, virtual memory, and so on), see [Important system configuration](important-system-configuration.md) and the pages linked from there.
+
+Where to configure system settings depends on how {{es}} is installed and started, and which operating system you are using:
+
+* When using the `.zip` or `.tar.gz` packages, {{es}} is typically started manually from a shell. In this case, system limits can be configured using `/etc/security/limits.conf` or by setting them directly in the shell using `ulimit` before starting {{es}}.
+
+* When using `.deb` or `.rpm` packages, Elasticsearch runs as a system service managed by systemd. In this case, system limits must be configured in the service definition (for example, using `LimitNOFILE` in a systemd override file).
 
 * Temporarily with [`ulimit`](#ulimit).
 * Permanently in [`/etc/security/limits.conf`](#limits.conf).
@@ -22,30 +29,44 @@
 
 ## `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 {{es}}. For example, to set the number of open file handles (`ulimit -n`) to 65,535, you can do the following:
+On Linux systems, you can use `ulimit` to change resource limits on a temporary basis. Limits usually need to be set as `root` before switching to the user that will run {{es}}.
+
+Common options for `ulimit` include:
+
+* `-n` — maximum number of open file descriptors
+* `-u` — maximum number of processes available to a single user
+* `-l` — maximum size of memory that may be locked into RAM
+* `-a` — show all current soft resource limits (use this to verify what is in effect)
+
+For the full list of options, run `help ulimit` in Bash.
+
+Use the option and value required for your setting (see the pages under [Important system configuration](important-system-configuration.md)). For example:
 
 ```sh
 sudo su  <1>
 ulimit -n 65535 <2>
-su elasticsearch <3>
+ulimit -u 4096 <3>
+ulimit -l unlimited <4>
+su elasticsearch <5>
 ```
 
 1. Become `root`.
-2. Change the max number of open files.
-3. Become the `elasticsearch` user in order to start {{es}}.
-
+2. Set the [open file descriptor limit](/deploy-manage/deploy/self-managed/file-descriptors.md) for this session.
+3. Set the [maximum number of threads](/deploy-manage/deploy/self-managed/max-number-of-threads.md) for this session.
+4. Allow [memory locking](/deploy-manage/deploy/self-managed/setup-configuration-memory.md#bootstrap-memory_lock) for this session.
+5. Become the user that will run {{es}} (for example `elasticsearch`) before starting the process.
 
 The new limit is only applied during the current session.
 
-You can consult all currently applied limits with `ulimit -a`.
-
 
 ## `/etc/security/limits.conf` [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,535, add the following line to the `limits.conf` file:
+On Linux systems, persistent limits can be set for a particular user by editing the `/etc/security/limits.conf` file. Add lines for the `elasticsearch` user (or the account that runs {{es}}) with the limit type and value your deployment requires. The exact limit name depends on what you are configuring. For example, you can configure `nofile` (open files), `nproc` (processes), or `memlock` (locked memory). Replace `<limit>` and `<value>` accordingly:
 
 ```sh
 elasticsearch  -  nofile  65535
+elasticsearch  -  nproc  4096
+elasticsearch  -  memlock  unlimited
 ```
 
 This change will only take effect the next time the `elasticsearch` user opens a new session.
@@ -74,26 +95,31 @@
 | RPM | `/etc/sysconfig/elasticsearch`|
 | Debian | `/etc/default/elasticsearch` | 
 
 However, system limits need to be specified via [systemd](#systemd).
 
+Use the topic pages under [Important system configuration](important-system-configuration.md) to determine which environment variables or JVM options you need (for example `ES_JAVA_OPTS`, `ES_TMPDIR`, or paths set in `jvm.options`).
+
 
 ## Systemd configuration [systemd]
 
 When using the RPM or Debian packages on systems that use [systemd](https://en.wikipedia.org/wiki/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.
 
-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:
+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. For example, for resource limits and environment variables, include:
 
 ```ini
 [Service]
+Environment="MY_VAR=my-value"
+LimitNOFILE=65535
+LimitNPROC=4096
 LimitMEMLOCK=infinity
 ```
 
+Replace the directives with those required for your deployment.
+
 Once finished, run the following command to reload units:
 
 ```sh
 sudo systemctl daemon-reload
 ```
-
-

deploy-manage/deploy/self-managed/setup-configuration-memory.md

@@ -66,7 +66,10 @@ GET _nodes?filter_path=**.mlockall
 
 If you see that `mlockall` is `false`, then it means that the `mlockall` request has failed. You will also see a line with more information in the logs with the words `Unable to lock JVM Memory`.
 
-The most probable reason, on Linux/Unix systems, is that the user running {{es}} doesn’t have permission to lock memory. This can be granted as follows:
+The most probable reason, on Linux/Unix systems, is that the user running {{es}} doesn’t have permission to lock memory. To change defaults on package-based installations, you can adjust limits by using `ulimit`, editing `/etc/security/limits.conf`, or through `systemd` service overrides, depending on whether limits are applied per session, per user, or for the service.
+
+You can grant permission to lock memory as follows:
+
 
 `.zip` and `.tar.gz`
 :   Set [`ulimit -l unlimited`](setting-system-settings.md#ulimit) as root before starting {{es}}. Alternatively, set `memlock` to `unlimited` in `/etc/security/limits.conf`: