//////////////////////////////////////////////////////////////////////////
//// This content is shared by all Elastic Beats. Make sure you keep the
//// descriptions here generic enough to work for all Beats that include
//// this file. When using cross references, make sure that the cross
//// references resolve correctly for any files that include this one.
//// Use the appropriate variables defined in the index.asciidoc file to
//// resolve Beat names: beatname_uc and beatname_lc
//// Use the following include to pull this content into a doc file:
//// include::../../libbeat/docs/keystore.asciidoc[]
//////////////////////////////////////////////////////////////////////////

[[keystore]]
=== Secrets keystore for secure settings

++++
<titleabbrev>Secrets keystore</titleabbrev>
++++

When you configure {beatname_uc}, you might need to specify sensitive settings,
such as passwords. Rather than relying on file system permissions to protect
these values, you can use the {beatname_uc} keystore to obfuscate stored secret
values for use in configuration settings.

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

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

`${KEY}`

Where KEY is the name of the key.

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

* In the configuration file, use `output.elasticsearch.password: "${ES_PWD}"`
* On the command line, use: `-E "output.elasticsearch.password=\${ES_PWD}"`

When {beatname_uc} unpacks the configuration, it resolves keys before resolving
environment variables and other variables.

Notice that the {beatname_uc} keystore differs from the Elasticsearch keystore.
Whereas the Elasticsearch keystore lets you store `elasticsearch.yml` values by
name, the {beatname_uc} keystore lets you specify arbitrary names that you can
reference in the {beatname_uc} configuration.

To create and manage keys, use the `keystore` command. See the
<<keystore-command,command reference>> for the full command syntax, including
optional flags.

NOTE: The `keystore` command must be run by the same user who will run
{beatname_uc}.

[float]
[[creating-keystore]]
=== Create a keystore

To create a secrets keystore, use:

["source","sh",subs="attributes"]
----------------------------------------------------------------
{beatname_lc} keystore create
----------------------------------------------------------------


{beatname_uc} creates the keystore in the directory defined by the `path.data`
configuration setting.

[float]
[[add-keys-to-keystore]]
=== Add keys

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

["source","sh",subs="attributes"]
----------------------------------------------------------------
{beatname_lc} keystore add ES_PWD
----------------------------------------------------------------


When prompted, enter a value for the key.

To overwrite an existing key's value, use the `--force` flag:

["source","sh",subs="attributes"]
----------------------------------------------------------------
{beatname_lc} keystore add ES_PWD --force
----------------------------------------------------------------

To pass the value through stdin, use the `--stdin` flag. You can also use
`--force`:

["source","sh",subs="attributes"]
----------------------------------------------------------------
cat /file/containing/setting/value | {beatname_lc} keystore add ES_PWD --stdin --force
----------------------------------------------------------------


[float]
[[list-settings]]
=== List keys

To list the keys defined in the keystore, use:

["source","sh",subs="attributes"]
----------------------------------------------------------------
{beatname_lc} keystore list
----------------------------------------------------------------


[float]
[[remove-settings]]
=== Remove keys

To remove a key from the keystore, use:

["source","sh",subs="attributes"]
----------------------------------------------------------------
{beatname_lc} keystore remove ES_PWD
----------------------------------------------------------------

