When you configure Logstash, you might need to specify sensitive settings orconfiguration, such as passwords. Rather than relying on file system permissionsto protect these values, you can use the Logstash keystore to securely storesecret values for use in configuration settings.

After adding a key and its secret value to the keystore, you can use the key inplace of the secret value when you configure sensitive settings.

The syntax for referencing keys is identical to the syntax forenvironment variables:

${KEY}

Where KEY is the name of the key.

For example, imagine that the keystore contains a key called ES_PWD with thevalue yourelasticsearchpassword:

Notice that the Logstash keystore differs from the Elasticsearch keystore.Whereas the Elasticsearch keystore lets you store elasticsearch.yml values byname, the Logstash keystore lets you specify arbitrary names that youcan reference in the Logstash configuration.

Referencing keystore data from pipelines.yml or the command line (-e)is not currently supported.

Referencing keystore data from centralized pipeline managementrequires each Logstash deployment to have a local copy of the keystore.

When Logstash parses the settings (logstash.yml) or configuration(/etc/logstash/conf.d/*.conf), it resolves keys from the keystore beforeresolving environment variables.

Keystore password

You can protect access to the Logstash keystore by storing a password in anenvironment variable called LOGSTASH_KEYSTORE_PASS. If you create the Logstashkeystore after setting this variable, the keystore will be password protected.This means that the environment variable needs to be accessible to the runninginstance of Logstash. This environment variable must also be correctly set forany users who need to issue keystore commands (add, list, remove, etc.).

Using a keystore password is recommended, but optional. The data will be encrypted even if youdo not set a password. However, it is highly recommended to configure thekeystore password and grant restrictive permissions to any files that maycontain the environment variable value. If you choose not to set a password, thenyou can skip the rest of this section.

For example:

set +o historyexport LOGSTASH_KEYSTORE_PASS=mypasswordset -o historybin/logstash-keystore create

This setup requires the user running Logstash to have the environment variableLOGSTASH_KEYSTORE_PASS=mypassword defined. If the environment variable is not defined,Logstash cannot access the the keystore.

When you run Logstash from an RPM or DEB package installation, the environmentvariables are sourced from /etc/sysconfig/logstash.

You might need to create /etc/sysconfig/logstash. This file should beowned by root with 600 permissions. The expected format of/etc/sysconfig/logstash is ENVIRONMENT_VARIABLE=VALUE, with one entry perline.

For other distributions, such as Docker or ZIP, see the documentation for yourruntime environment (Windows, Docker, etc) to learn how to set theenvironment variable for the user that runs Logstash. Ensure that theenvironment variable (and thus the password) is only accessible to that user.

Keystore location

The keystore must be located in Logstash’s path.settings directory. This isthe same directory that contains the logstash.yml file. When performing anyoperation against the keystore, it is recommended to set path.settings for thekeystore command. For example, to create a keystore on a RPM/DEB installation:

set +o historyexport LOGSTASH_KEYSTORE_PASS=mypasswordset -o historysudo -E /usr/share/logstash/bin/logstash-keystore --path.settings /etc/logstash create

See Logstash Directory Layout for more about the default directory locations.

You will see a warning if the path.settings is not pointed to the same directoryas the logstash.yml.

Create a keystore

To create a secrets keystore, use the create:

bin/logstash-keystore create

Creates the keystore in the directory defined by the path.settingsconfiguration setting.

It is recommended that you set a keystore passwordwhen creating the keystore.

Add keys

To store sensitive values, such as authentication credentials for Elasticsearch,use the add command:

bin/logstash-keystore add ES_PWD

When prompted, enter a value for the key.

List keys

To list the keys defined in the keystore, use:

bin/logstash-keystore list

Remove keys

To remove a key from the keystore, use:

bin/logstash-keystore remove ES_PWD