From 14795813b7de89b650861fb53e213f7ce20e9b8f Mon Sep 17 00:00:00 2001
From: Colleen McGinnis <colleen.mcginnis@elastic.co>
Date: Mon, 27 Nov 2023 16:11:31 -0600
Subject: [PATCH] restore old keystore doc

---
 docs/keystore.asciidoc               | 107 +++++++++++++++++++++++++++
 docs/setting-up-and-running.asciidoc |   2 +
 2 files changed, 109 insertions(+)
 create mode 100644 docs/keystore.asciidoc

diff --git a/docs/keystore.asciidoc b/docs/keystore.asciidoc
new file mode 100644
index 00000000000..2cd74ddea6a
--- /dev/null
+++ b/docs/keystore.asciidoc
@@ -0,0 +1,107 @@
+[[keystore]]
+=== Secrets keystore for secure settings
+
+++++
+<titleabbrev>Secrets keystore</titleabbrev>
+++++
+
+When you configure APM Server, 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 APM Server keystore to securely store 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 APM Server unpacks the configuration, it resolves keys before resolving
+environment variables and other variables.
+
+Notice that the APM Server keystore differs from the {es} keystore.
+Whereas the {es} keystore lets you store `elasticsearch.yml` values by
+name, the APM Server keystore lets you specify arbitrary names that you can
+reference in the APM Server 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
+APM Server.
+
+[discrete]
+[[creating-keystore]]
+=== Create a keystore
+
+To create a secrets keystore, use:
+
+[source,sh]
+-----
+apm-server keystore create
+-----
+
+APM Server creates the keystore in the directory defined by the `path.data`
+configuration setting.
+
+[discrete]
+[[add-keys-to-keystore]]
+=== Add keys
+
+To store sensitive values, such as authentication credentials for {es},
+use the `keystore add` command:
+
+[source,sh]
+-----
+apm-server 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]
+-----
+apm-server keystore add ES_PWD --force
+-----
+
+To pass the value through stdin, use the `--stdin` flag. You can also use
+`--force`:
+
+[source,sh]
+-----
+cat /file/containing/setting/value | apm-server keystore add ES_PWD --stdin --force
+-----
+
+[discrete]
+[[list-settings]]
+=== List keys
+
+To list the keys defined in the keystore, use:
+
+[source,sh]
+-----
+apm-server keystore list
+-----
+
+[discrete]
+[[remove-settings]]
+=== Remove keys
+
+To remove a key from the keystore, use:
+
+[source,sh]
+-----
+apm-server keystore remove ES_PWD
+-----
diff --git a/docs/setting-up-and-running.asciidoc b/docs/setting-up-and-running.asciidoc
index 796cda351ed..057ae4c7c2e 100644
--- a/docs/setting-up-and-running.asciidoc
+++ b/docs/setting-up-and-running.asciidoc
@@ -18,6 +18,8 @@ This section includes additional information on how to set up and run APM Server
 
 include::{docdir}/shared-directory-layout.asciidoc[]
 
+include::{docdir}/keystore.asciidoc[]
+
 include::{docdir}/command-reference.asciidoc[]
 
 include::{docdir}/data-ingestion.asciidoc[]