[[elasticsearch-keystore]]
== elasticsearch-keystore

The `elasticsearch-keystore` command manages <<secure-settings,secure settings>>
in the {es} keystore.

[discrete]
[[elasticsearch-keystore-synopsis]]
=== Synopsis

[source,shell]
--------------------------------------------------
bin/elasticsearch-keystore
([add <setting>] [--stdin] |
[add-file <setting> <path>] | [create] |
[list] | [remove <setting>] | [upgrade])
[-h, --help] ([-s, --silent] | [-v, --verbose])
--------------------------------------------------

[discrete]
[[elasticsearch-keystore-description]]
=== Description

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.

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
is no validation to block unsupported settings from the keystore and they can
cause {es} to fail to start. To see whether a setting is supported in the
keystore, see the setting reference.

[discrete]
[[elasticsearch-keystore-parameters]]
=== Parameters

`add <setting>`:: Adds settings to the keystore. By default, you are prompted
for the value of the setting.

`add-file <setting> <path>`:: Adds a file to the keystore.

`create`:: Creates the keystore.

`-h, --help`:: Returns all of the command parameters.

`list`:: Lists the settings in the keystore.

`remove <setting>`:: Removes a setting from the keystore.

`-s, --silent`:: Shows minimal output.

`--stdin`:: When used with the `add` parameter, you can pass the setting value
through standard input (stdin). See <<add-string-to-keystore>>.

`upgrade`:: Upgrades the internal format of the keystore.

`-v, --verbose`:: Shows verbose output.

[discrete]
[[elasticsearch-keystore-examples]]
=== Examples

[discrete]
[[creating-keystore]]
==== Create the keystore

To create the `elasticsearch.keystore`, use the `create` command:

[source,sh]
----------------------------------------------------------------
bin/elasticsearch-keystore create
----------------------------------------------------------------

A `elasticsearch.keystore` file is created alongside the `elasticsearch.yml`
file.

[discrete]
[[list-settings]]
==== List settings in the keystore

To list the settings in the keystore, use the `list` command.

[source,sh]
----------------------------------------------------------------
bin/elasticsearch-keystore list
----------------------------------------------------------------

[discrete]
[[add-string-to-keystore]]
==== Add settings to the keystore

Sensitive string settings, like authentication credentials for Cloud plugins,
can be added with the `add` command:

[source,sh]
----------------------------------------------------------------
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:

[source,sh]
----------------------------------------------------------------
cat /file/containing/setting/value | bin/elasticsearch-keystore add --stdin the.setting.name.to.set
----------------------------------------------------------------

[discrete]
[[add-file-to-keystore]]
==== Add files to the keystore

You can add sensitive files, like authentication key files for Cloud plugins,
using the `add-file` command. Be sure to include your file path as an argument
after the setting name.

[source,sh]
----------------------------------------------------------------
bin/elasticsearch-keystore add-file the.setting.name.to.set /path/example-file.json
----------------------------------------------------------------

[discrete]
[[remove-settings]]
==== Remove settings from the keystore

To remove a setting from the keystore, use the `remove` command:

[source,sh]
----------------------------------------------------------------
bin/elasticsearch-keystore remove the.setting.name.to.remove
----------------------------------------------------------------

[discrete]
[[keystore-upgrade]]
==== Upgrade the keystore

Occasionally, the internal format of the keystore changes. When {es} is
installed from a package manager, an upgrade of the on-disk keystore to the new
format is done during package upgrade. In other cases, {es} performs the upgrade
during node startup. This requires that {es} has write permissions to the
directory that contains the keystore. Alternatively, you can manually perform
such an upgrade by using the `upgrade` command:

[source,sh]
----------------------------------------------------------------
bin/elasticsearch-keystore upgrade
----------------------------------------------------------------