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.

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.

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

bin/elasticsearch-keystore create

The file elasticsearch.keystore will be created alongside elasticsearch.yml.

A list of the settings in the keystore is available with the list command:

bin/elasticsearch-keystore list

Sensitive string settings, like authentication credentials for cloud plugins, can be added using the add command:

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:

cat /file/containing/setting/value | bin/elasticsearch-keystore add --stdin the.setting.name.to.set

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.

bin/elasticsearch-keystore add-file the.setting.name.to.set /path/example-file.json

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

bin/elasticsearch-keystore remove the.setting.name.to.remove

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:

bin/elasticsearch-keystore upgrade

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:

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.