Add documentation for keystore startup prompting (#50821)

When a keystore is password-protected, Elasticsearch will prompt at
startup. This commit adds documentation for this prompt for the archive,
systemd, and Docker cases.

Co-authored-by: Lisa Cawley <[email protected]>

Author: williamrandolph

docs/reference/commands/keystore.asciidoc

@@ -11,9 +11,9 @@ in the {es} keystore.
 [source,shell]
 --------------------------------------------------
 bin/elasticsearch-keystore
-([add <setting>] [--stdin] |
-[add-file <setting> <path>] | [create] |
-[list] | [remove <setting>] | [upgrade])
+([add <setting>] [-f] [--stdin] |
+[add-file <setting> <path>] | [create] [-p] |
+[list] | [passwd] | [remove <setting>] | [upgrade])
 [-h, --help] ([-s, --silent] | [-v, --verbose])
 --------------------------------------------------
 
@@ -26,6 +26,9 @@ IMPORTANT: This command should be run as the user that will run {es}.
 Currently, all secure settings are node-specific settings that must have the
 same value on every node. Therefore you must run this command on every node.
 
+When the keystore is password-protected, you must supply the password each time
+{es} starts.
+
 Modifications to the keystore do not take effect until you restart {es}.
 
 Only some settings are designed to be read from the keystore. However, there
@@ -38,17 +41,36 @@ keystore, see the setting reference.
 === Parameters
 
 `add <setting>`:: Adds settings to the keystore. By default, you are prompted
-for the value of the setting.
+for the value of the setting. If the keystore is password protected, you are
+also prompted to enter the password. If the setting already exists in the
+keystore, you must confirm that you want to overwrite the current value. If the
+keystore does not exist, you must confirm that you want to create a keystore. To
+avoid these two confirmation prompts, use the `-f` parameter.
 
 `add-file <setting> <path>`:: Adds a file to the keystore.
 
 `create`:: Creates the keystore.
 
+`-f`:: When used with the `add` parameter, the command no longer prompts you
+before overwriting existing entries in the keystore. Also, if you haven't
+created a keystore yet, it creates a keystore that is obfuscated but not
+password protected.
+
 `-h, --help`:: Returns all of the command parameters.
 
-`list`:: Lists the settings in the keystore.
+`list`:: Lists the settings in the keystore. If the keystore is password
+protected, you are prompted to enter the password.
+
+`-p`:: When used with the `create` parameter, the command prompts you to enter a
+keystore password. If you don't specify the `-p` flag or if you enter an empty
+password, the keystore is obfuscated but not password protected.
+
+`passwd`:: Changes or sets the keystore password. If the keystore is password
+protected, you are prompted to enter the current password and the new one. You
+can optionally use an empty string to remove the password. If the keystore is
+not password protected, you can use this command to set a password.
 
-`remove <setting>:: Removes a setting from the keystore.
+`remove <setting>`:: Removes a setting from the keystore.
 
 `-s, --silent`:: Shows minimal output.
 
@@ -71,11 +93,26 @@ To create the `elasticsearch.keystore`, use the `create` command:
 
 [source,sh]
 ----------------------------------------------------------------
-bin/elasticsearch-keystore create
+bin/elasticsearch-keystore create -p
+----------------------------------------------------------------
+
+You are prompted to enter the keystore password. A password-protected
+`elasticsearch.keystore` file is created alongside the `elasticsearch.yml` file.
+
+[discrete]
+[[changing-keystore-password]]
+==== Change the password of the keystore
+
+To change the password of the `elasticsearch.keystore`, use the `passwd` command:
+
+[source,sh]
+----------------------------------------------------------------
+bin/elasticsearch-keystore passwd
 ----------------------------------------------------------------
 
-A `elasticsearch.keystore` file is created alongside the `elasticsearch.yml`
-file.
+If the {es} keystore is password protected, you are prompted to enter the
+current password and then enter the new one. If it is not password protected,
+you are prompted to set a password.
 
 [discrete]
 [[list-settings]]
@@ -88,6 +125,9 @@ To list the settings in the keystore, use the `list` command.
 bin/elasticsearch-keystore list
 ----------------------------------------------------------------
 
+If the {es} keystore is password protected, you are prompted to enter the
+password.
+
 [discrete]
 [[add-string-to-keystore]]
 ==== Add settings to the keystore
@@ -100,8 +140,10 @@ can be added with the `add` command:
 bin/elasticsearch-keystore add the.setting.name.to.set
 ----------------------------------------------------------------
 
-You are prompted to enter the value of the setting. To pass the value
-through standard input (stdin), use the `--stdin` flag:
+You are prompted to enter the value of the setting. If the {es} keystore is
+password protected, you are also prompted to enter the password.
+
+To pass the setting value through standard input (stdin), use the `--stdin` flag:
 
 [source,sh]
 ----------------------------------------------------------------
@@ -121,6 +163,9 @@ after the setting name.
 bin/elasticsearch-keystore add-file the.setting.name.to.set /path/example-file.json
 ----------------------------------------------------------------
 
+If the {es} keystore is password protected, you are prompted to enter the
+password.
+
 [discrete]
 [[remove-settings]]
 ==== Remove settings from the keystore
@@ -132,6 +177,9 @@ To remove a setting from the keystore, use the `remove` command:
 bin/elasticsearch-keystore remove the.setting.name.to.remove
 ----------------------------------------------------------------
 
+If the {es} keystore is password protected, you are prompted to enter the
+password.
+
 [discrete]
 [[keystore-upgrade]]
 ==== Upgrade the keystore

docs/reference/setup/install/docker.asciidoc

@@ -360,6 +360,25 @@ IMPORTANT: The container **runs {es} as user `elasticsearch` using
 uid:gid `1000:0`**. Bind mounted host directories and files must be accessible by this user,
 and the data and log directories must be writable by this user.
 
+[[docker-keystore-bind-mount]]
+===== Mounting an {es} keystore
+
+By default, {es} will auto-generate a keystore file for secure settings. This
+file is obfuscated but not encrypted. If you want to encrypt your
+<<secure-settings,secure settings>> with a password, you must use the
+`elasticsearch-keystore` utility to create a password-protected keystore and
+bind-mount it to the container as
+`/usr/share/elasticsearch/config/elasticsearch.keystore`. In order to provide
+the Docker container with the password at startup, set the Docker environment
+value `KEYSTORE_PASSWORD` to the value of your password. For example, a `docker
+run` command might have the following options:
+
+[source, sh]
+--------------------------------------------
+-v full_path_to/elasticsearch.keystore:/usr/share/elasticsearch/config/elasticsearch.keystore
+-E KEYSTORE_PASSWORD=mypassword
+--------------------------------------------
+
 [[_c_customized_image]]
 ===== Using custom Docker images
 In some environments, it might make more sense to prepare a custom image that contains

docs/reference/setup/install/systemd.asciidoc

@@ -21,6 +21,19 @@ These commands provide no feedback as to whether Elasticsearch was started
 successfully or not. Instead, this information will be written in the log
 files located in `/var/log/elasticsearch/`.
 
+If you have password-protected your {es} keystore, you will need to provide
+`systemd` with the keystore password using a local file and systemd environment
+variables. This local file should be protected while it exists and may be
+safely deleted once Elasticsearch is up and running.
+
+[source,sh]
+-----------------------------------------------------------------------------------
+echo "keystore_password" > /path/to/my_pwd_file.tmp
+chmod 600 /path/to/my_pwd_file.tmp
+sudo systemctl set-environment ES_KEYSTORE_PASSPHRASE_FILE=/path/to/my_pwd_file.tmp
+sudo systemctl start elasticsearch.service
+-----------------------------------------------------------------------------------
+
 By default the Elasticsearch service doesn't log information in the `systemd`
 journal. To enable `journalctl` logging, the `--quiet` option must be removed
  from the `ExecStart` command line in the `elasticsearch.service` file.

docs/reference/setup/install/targz-daemon.asciidoc

@@ -8,13 +8,17 @@ the process ID in a file using the `-p` option:
 ./bin/elasticsearch -d -p pid
 --------------------------------------------
 
+If you have password-protected the {es} keystore, you will be prompted
+to enter the keystore's password. See <<secure-settings>> for more
+details.
+
 Log messages can be found in the `$ES_HOME/logs/` directory.
 
 To shut down Elasticsearch, kill the process ID recorded in the `pid` file:
 
 [source,sh]
 --------------------------------------------
-pkill -F pid 
+pkill -F pid
 --------------------------------------------
 
 NOTE: The startup scripts provided in the <<rpm,RPM>> and <<deb,Debian>>

docs/reference/setup/install/targz-start.asciidoc

@@ -7,6 +7,10 @@ Elasticsearch can be started from the command line as follows:
 ./bin/elasticsearch
 --------------------------------------------
 
+If you have password-protected the {es} keystore, you will be prompted
+to enter the keystore's password. See <<secure-settings>> for more
+details.
+
 By default, Elasticsearch runs in the foreground, prints its logs to the
 standard output (`stdout`), and can be stopped by pressing `Ctrl-C`.
 

docs/reference/setup/install/zip-windows-start.asciidoc

@@ -7,5 +7,8 @@ Elasticsearch can be started from the command line as follows:
 .\bin\elasticsearch.bat
 --------------------------------------------
 
+If you have password-protected the {es} keystore, you will be prompted to
+enter the keystore's password. See <<secure-settings>> for more details.
+
 By default, Elasticsearch runs in the foreground, prints its logs to `STDOUT`,
 and can be stopped by pressing `Ctrl-C`.