Deprecate bootstrap.mlockall

The setting bootstrap.mlockall is useful on both POSIX-like systems
(POSIX mlockall) and Windows (Win32 VirtualLock). But mlockall is really
a POSIX only thing so the name should not be tied POSIX. This commit
deprecates the setting in favor of "bootstrap.memory_lock".

Relates #18671

Author: jasontedor

core/src/main/java/org/elasticsearch/bootstrap/Bootstrap.java

@@ -28,6 +28,7 @@
 import org.elasticsearch.common.cli.Terminal;
 import org.elasticsearch.common.inject.CreationException;
 import org.elasticsearch.common.lease.Releasables;
+import org.elasticsearch.common.logging.DeprecationLogger;
 import org.elasticsearch.common.logging.ESLogger;
 import org.elasticsearch.common.logging.Loggers;
 import org.elasticsearch.common.logging.log4j.LogConfigurator;
@@ -141,8 +142,23 @@ static void initializeProbes() {
     }
 
     private void setup(boolean addShutdownHook, Settings settings, Environment environment) throws Exception {
+        final ESLogger logger = Loggers.getLogger(Bootstrap.class);
+        final DeprecationLogger deprecationLogger = new DeprecationLogger(logger);
+
+        final Boolean mlockall = settings.getAsBoolean("bootstrap.mlockall", null);
+        if (mlockall != null) {
+            deprecationLogger.deprecated("setting [bootstrap.mlockall] is deprecated; use [bootstrap.memory_lock]");
+        }
+
+        final Boolean memoryLock = settings.getAsBoolean("bootstrap.memory_lock", null);
+        // both bootstrap.mlockall and bootstrap.memory_lock are set, refuse to start
+        if (mlockall != null && memoryLock != null) {
+            throw new IllegalArgumentException("both [bootstrap.mlockall] and [bootstrap.memory_lock] configured,"
+                + " just use [bootstrap.memory_lock]");
+        }
+
         initializeNatives(environment.tmpFile(),
-                          settings.getAsBoolean("bootstrap.mlockall", false),
+                          memoryLock != null ? memoryLock : mlockall != null ? mlockall : false,
                           settings.getAsBoolean("bootstrap.seccomp", true),
                           settings.getAsBoolean("bootstrap.ctrlhandler", true));
 

distribution/src/main/packaging/env/elasticsearch

@@ -63,7 +63,7 @@ ES_STARTUP_SLEEP_TIME=${packaging.elasticsearch.startup.sleep.time}
 #MAX_OPEN_FILES=${packaging.os.max.open.files}
 
 # The maximum number of bytes of memory that may be locked into RAM
-# Set to "unlimited" if you use the 'bootstrap.mlockall: true' option
+# Set to "unlimited" if you use the 'bootstrap.memory_lock: true' option
 # in elasticsearch.yml (ES_HEAP_SIZE  must also be set).
 # When using Systemd, the LimitMEMLOCK property must be set
 # in ${packaging.elasticsearch.systemd.dir}/elasticsearch.service

distribution/src/main/packaging/systemd/elasticsearch.service

@@ -33,7 +33,7 @@ StandardError=inherit
 LimitNOFILE=${packaging.os.max.open.files}
 
 # Specifies the maximum number of bytes of memory that may be locked into RAM
-# Set to "infinity" if you use the 'bootstrap.mlockall: true' option
+# Set to "infinity" if you use the 'bootstrap.memory_lock: true' option
 # in elasticsearch.yml and 'MAX_LOCKED_MEMORY=unlimited' in ${packaging.env.file}
 #LimitMEMLOCK=infinity
 

distribution/src/main/resources/config/elasticsearch.yml

@@ -40,7 +40,7 @@
 #
 # Lock the memory on startup:
 #
-# bootstrap.mlockall: true
+# bootstrap.memory_lock: true
 #
 # Make sure that the `ES_HEAP_SIZE` environment variable is set to about half the memory
 # available on the system and that the owner of the process is allowed to use this limit.

docs/reference/migration/migrate_2_4.asciidoc

@@ -0,0 +1,11 @@
+[[breaking-changes-2.4]]
+== Breaking changes in 2.4
+
+[[breaking_24_settings]]
+[float]
+=== Settings
+
+The setting `bootstrap.mlockall` has been renamed to
+<<bootstrap.memory_lock,`bootstrap.memory_lock`>>. Future versions of
+Elasticsearch will refuse to start if `bootstrap.mlockall` is set. You
+can switch to the new setting now.

docs/reference/setup/as-a-service.asciidoc

@@ -17,7 +17,7 @@ Each package features a configuration file, which allows you to set the followin
 `ES_HEAP_NEWSIZE`::       The size of the new generation heap
 `ES_DIRECT_SIZE`::        The maximum size of the direct memory
 `MAX_OPEN_FILES`::        Maximum number of open files, defaults to `65536`
-`MAX_LOCKED_MEMORY`::     Maximum locked memory size. Set to "unlimited" if you use the bootstrap.mlockall option in elasticsearch.yml. You must also set ES_HEAP_SIZE.
+`MAX_LOCKED_MEMORY`::     Maximum locked memory size. Set to "unlimited" if you use the bootstrap.memory_lock option in elasticsearch.yml. You must also set ES_HEAP_SIZE.
 `MAX_MAP_COUNT`::         Maximum number of memory map areas a process may have. If you use `mmapfs` as index store type, make sure this is set to a high value. For more information, check the https://github.com/torvalds/linux/blob/master/Documentation/sysctl/vm.txt[linux kernel documentation] about `max_map_count`. This is set via `sysctl` before starting elasticsearch. Defaults to `65535`
 `LOG_DIR`::               Log directory, defaults to `/var/log/elasticsearch`
 `DATA_DIR`::              Data directory, defaults to `/var/lib/elasticsearch`

docs/reference/setup/configuration.asciidoc

@@ -121,7 +121,7 @@ to the `config/elasticsearch.yml` file:
 
 [source,yaml]
 --------------
-bootstrap.mlockall: true
+bootstrap.memory_lock: true
 --------------
 
 After starting Elasticsearch, you can see whether this setting was applied