From ae192256985f6b50f7dc8f003147ff284733ba29 Mon Sep 17 00:00:00 2001
From: Juan A <juan@opbeat.com>
Date: Mon, 5 Feb 2018 10:49:30 +0100
Subject: [PATCH] document and git-ignore the new keystore provided by beats

---
 .gitignore                               |   2 +-
 docs/copied-from-beats/keystore.asciidoc | 116 +++++++++++++++++++++++
 docs/setting-up-and-running.asciidoc     |   2 +
 3 files changed, 119 insertions(+), 1 deletion(-)
 create mode 100644 docs/copied-from-beats/keystore.asciidoc

diff --git a/.gitignore b/.gitignore
index 7ac68950c6d..53860391421 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,7 +7,7 @@
 .DS_Store
 *.pyc
 /apm-server.iml
-
+/apm-server.keystore
 /approvals
 /apm-server
 /apm-server.test
diff --git a/docs/copied-from-beats/keystore.asciidoc b/docs/copied-from-beats/keystore.asciidoc
new file mode 100644
index 00000000000..faab29222a8
--- /dev/null
+++ b/docs/copied-from-beats/keystore.asciidoc
@@ -0,0 +1,116 @@
+//////////////////////////////////////////////////////////////////////////
+//// 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
+
+When you configure {beatname_uc}, you might need to specify sensitive settings,
+such as passwords. Relying on the file system to protect these values is not
+sufficient. {beatname_uc} provides a keystore for storing secret values to use
+in configuration settings.
+
+Unlike the Elasticsearch keystore, the {beatname_uc} keystore does not store
+actual configuration settings. Instead, you add a key and secret value to the
+keystore, and then 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.  
+
+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.config`
+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} remove ES_PWD
+----------------------------------------------------------------
+
diff --git a/docs/setting-up-and-running.asciidoc b/docs/setting-up-and-running.asciidoc
index e9caacbb35a..6ca2a7d6291 100644
--- a/docs/setting-up-and-running.asciidoc
+++ b/docs/setting-up-and-running.asciidoc
@@ -86,6 +86,8 @@ include::./security.asciidoc[]
 
 include::./dashboards.asciidoc[]
 
+include::./copied-from-beats/keystore.asciidoc[]
+
 include::./copied-from-beats/command-reference.asciidoc[]
 
 include::./copied-from-beats/shared-directory-layout.asciidoc[]