147 lines
5.6 KiB
Plaintext
147 lines
5.6 KiB
Plaintext
[[secure-settings]]
|
|
=== Secure settings
|
|
|
|
Some settings are sensitive, and relying on filesystem permissions to protect
|
|
their values is not sufficient. For this use case, Elasticsearch provides a
|
|
keystore and the `elasticsearch-keystore` tool to manage the settings in the keystore.
|
|
|
|
NOTE: All commands here should be run as the user which will run Elasticsearch.
|
|
|
|
IMPORTANT: Only some settings are designed to be read from the keystore. However,
|
|
the keystore has no validation to block unsupported settings.
|
|
Adding unsupported settings to the keystore will cause {es}
|
|
Additional unsupported settings being added to the keystore will cause Elasticsearch
|
|
to fail to start. See documentation for each setting to see if it is supported
|
|
as part of the keystore.
|
|
|
|
NOTE: All the modifications to the keystore take affect only after restarting
|
|
Elasticsearch.
|
|
|
|
NOTE: The elasticsearch keystore currently only provides obfuscation. In the future,
|
|
password protection will be added.
|
|
|
|
These settings, just like the regular ones in the `elasticsearch.yml` config file,
|
|
need to be specified on each node in the cluster. Currently, all secure settings
|
|
are node-specific settings that must have the same value on every node.
|
|
|
|
[float]
|
|
[[creating-keystore]]
|
|
=== Creating the keystore
|
|
|
|
To create the `elasticsearch.keystore`, use the `create` command:
|
|
|
|
[source,sh]
|
|
----------------------------------------------------------------
|
|
bin/elasticsearch-keystore create
|
|
----------------------------------------------------------------
|
|
|
|
The file `elasticsearch.keystore` will be created alongside `elasticsearch.yml`.
|
|
|
|
[float]
|
|
[[list-settings]]
|
|
=== Listing settings in the keystore
|
|
|
|
A list of the settings in the keystore is available with the `list` command:
|
|
|
|
[source,sh]
|
|
----------------------------------------------------------------
|
|
bin/elasticsearch-keystore list
|
|
----------------------------------------------------------------
|
|
|
|
[float]
|
|
[[add-string-to-keystore]]
|
|
=== Adding string settings
|
|
|
|
Sensitive string settings, like authentication credentials for cloud
|
|
plugins, can be added using the `add` command:
|
|
|
|
[source,sh]
|
|
----------------------------------------------------------------
|
|
bin/elasticsearch-keystore add the.setting.name.to.set
|
|
----------------------------------------------------------------
|
|
|
|
The tool will prompt for the value of the setting. To pass the value
|
|
through stdin, use the `--stdin` flag:
|
|
|
|
[source,sh]
|
|
----------------------------------------------------------------
|
|
cat /file/containing/setting/value | bin/elasticsearch-keystore add --stdin the.setting.name.to.set
|
|
----------------------------------------------------------------
|
|
|
|
[float]
|
|
[[add-file-to-keystore]]
|
|
=== Adding file settings
|
|
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
|
|
----------------------------------------------------------------
|
|
|
|
[float]
|
|
[[remove-settings]]
|
|
=== Removing settings
|
|
|
|
To remove a setting from the keystore, use the `remove` command:
|
|
|
|
[source,sh]
|
|
----------------------------------------------------------------
|
|
bin/elasticsearch-keystore remove the.setting.name.to.remove
|
|
----------------------------------------------------------------
|
|
|
|
[float]
|
|
[[keystore-upgrade]]
|
|
=== Upgrading the keystore
|
|
|
|
Occasionally, the internal format of the keystore changes. When Elasticsearch 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, Elasticsearch will
|
|
perform such an upgrade during node startup. This requires that Elasticsearch
|
|
have 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
|
|
----------------------------------------------------------------
|
|
|
|
[float]
|
|
[[reloadable-secure-settings]]
|
|
=== Reloadable secure settings
|
|
|
|
Just like the settings values in `elasticsearch.yml`, changes to the
|
|
keystore contents are not automatically applied to the running
|
|
elasticsearch node. Re-reading settings requires a node restart.
|
|
However, certain secure settings are marked as *reloadable*. Such settings
|
|
can be re-read and applied on a running node.
|
|
|
|
The values of all secure settings, *reloadable* or not, must be identical
|
|
across all cluster nodes. After making the desired secure settings changes,
|
|
using the `bin/elasticsearch-keystore add` command, call:
|
|
|
|
[source,console]
|
|
----
|
|
POST _nodes/reload_secure_settings
|
|
----
|
|
|
|
This API will decrypt and re-read the entire keystore, on every cluster node,
|
|
but only the *reloadable* secure settings will be applied. Changes to other
|
|
settings will not go into effect until the next restart. Once the call returns,
|
|
the reload has been completed, meaning that all internal datastructures dependent
|
|
on these settings have been changed. Everything should look as if the settings
|
|
had the new value from the start.
|
|
|
|
When changing multiple *reloadable* secure settings, modify all of them, on
|
|
each cluster node, and then issue a `reload_secure_settings` call, instead
|
|
of reloading after each modification.
|
|
|
|
There are reloadable secure settings for:
|
|
|
|
* {plugins}/repository-azure-client-settings.html[The Azure repository plugin]
|
|
* {plugins}/discovery-ec2-usage.html#_configuring_ec2_discovery[The EC2 discovery plugin]
|
|
* {plugins}/repository-gcs-client.html[The GCS repository plugin]
|
|
* {plugins}/repository-s3-client.html[The S3 repository plugin]
|