diff --git a/docs/reference/commands/keystore.asciidoc b/docs/reference/commands/keystore.asciidoc index 7b2df6ee24c77..085f8acb7adcb 100644 --- a/docs/reference/commands/keystore.asciidoc +++ b/docs/reference/commands/keystore.asciidoc @@ -11,9 +11,9 @@ in the {es} keystore. [source,shell] -------------------------------------------------- bin/elasticsearch-keystore -([add ] [--stdin] | -[add-file ] | [create] | -[list] | [remove ] | [upgrade]) +([add ] [-f] [--stdin] | +[add-file ] | [create] [-p] | +[list] | [passwd] | [remove ] | [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,15 +41,34 @@ keystore, see the setting reference. === Parameters `add `:: 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 `:: 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 `:: Removes a setting from the keystore. @@ -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 diff --git a/docs/reference/setup/install/docker.asciidoc b/docs/reference/setup/install/docker.asciidoc index 537dec2904070..766c71d2840f4 100644 --- a/docs/reference/setup/install/docker.asciidoc +++ b/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 +<> 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 diff --git a/docs/reference/setup/install/systemd.asciidoc b/docs/reference/setup/install/systemd.asciidoc index bf94e95fb63df..274a599e68f09 100644 --- a/docs/reference/setup/install/systemd.asciidoc +++ b/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. diff --git a/docs/reference/setup/install/targz-daemon.asciidoc b/docs/reference/setup/install/targz-daemon.asciidoc index 1325503687a07..2ccd0519945b4 100644 --- a/docs/reference/setup/install/targz-daemon.asciidoc +++ b/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 <> 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 <> and <> diff --git a/docs/reference/setup/install/targz-start.asciidoc b/docs/reference/setup/install/targz-start.asciidoc index 907b2a7317d79..cf90e05d173f6 100644 --- a/docs/reference/setup/install/targz-start.asciidoc +++ b/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 <> 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`. diff --git a/docs/reference/setup/install/zip-windows-start.asciidoc b/docs/reference/setup/install/zip-windows-start.asciidoc index 7ecea449d2895..718259e4b77fc 100644 --- a/docs/reference/setup/install/zip-windows-start.asciidoc +++ b/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 <> for more details. + By default, Elasticsearch runs in the foreground, prints its logs to `STDOUT`, and can be stopped by pressing `Ctrl-C`.