From e0908f55a9ddc35767075e2f5b53af7c2c93e9a0 Mon Sep 17 00:00:00 2001
From: Karen Metts <35154725+karenzone@users.noreply.github.com>
Date: Wed, 21 Jul 2021 10:54:54 -0400
Subject: [PATCH] Doc: Fix typo and adjust keystore text 7.x #13095

---
 docs/static/keystore.asciidoc | 56 +++++++++++++++++++++--------------
 1 file changed, 34 insertions(+), 22 deletions(-)

diff --git a/docs/static/keystore.asciidoc b/docs/static/keystore.asciidoc
index aa59f83df..ce6a9f0b1 100644
--- a/docs/static/keystore.asciidoc
+++ b/docs/static/keystore.asciidoc
@@ -12,15 +12,30 @@ place of the secret value when you configure sensitive settings.
 The syntax for referencing keys is identical to the syntax for
 <<environment-variables, environment variables>>:
 
-`${KEY}`
+[source,txt]
+-----
+${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`:
+**Example**
+ 
+Imagine that the keystore contains a key called `ES_PWD` with the value `yourelasticsearchpassword`.
 
-* In configuration files, use: `output { elasticsearch {...password => "${ES_PWD}" } } }`
-* In `logstash.yml`, use: `xpack.management.elasticsearch.password: ${ES_PWD}`
+In configuration files, use: 
+
+[source,shell]
+-----
+output { elasticsearch {...password => "${ES_PWD}" } } } 
+-----
+
+In `logstash.yml`, use:
+
+[source,shell]
+-----
+xpack.management.elasticsearch.password: ${ES_PWD}
+-----  
 
 Notice that the Logstash keystore differs from the Elasticsearch keystore.
 Whereas the Elasticsearch keystore lets you store `elasticsearch.yml` values by
@@ -46,12 +61,8 @@ When Logstash parses the settings (`logstash.yml`) or configuration
 (`/etc/logstash/conf.d/*.conf`), it resolves keys from the keystore before
 resolving environment variables.
 
-// TODO: add keystore-command to running-logstash-command-line.asciidoc
-// To create and manage keys, use the `keystore` command. See the
-// <<keystore-command,command reference>> for the full command syntax, including
-// optional flags.
 
-[float]
+[discrete]
 [[keystore-password]]
 === Keystore password
 
@@ -94,11 +105,11 @@ runtime environment (Windows, Docker, etc) to learn how to set the
 environment variable for the user that runs Logstash. Ensure that the
 environment variable (and thus the password) is only accessible to that user.
 
-[float]
+[discrete]
 [[keystore-location]]
 === Keystore location
 
-The keystore must be located in Logstash's `path.settings` directory. This is
+The keystore must be located in the Logstash `path.settings` directory. This is
 the same directory that contains the `logstash.yml` file. When performing any
 operation against the keystore, it is recommended to set `path.settings` for the
 keystore command. For example, to create a keystore on a RPM/DEB installation:
@@ -116,24 +127,25 @@ See <<dir-layout>> for more about the default directory locations.
 NOTE: You will see a warning if the `path.settings` is not pointed to the same directory
 as the `logstash.yml`.
 
-[float]
+[discrete]
 [[creating-keystore]]
-=== Create a keystore
+=== Create or overwrite a keystore
 
-To create a secrets keystore, use the `create`:
+The `create` command creates a new keystore or overwrites an existing keystore:
 
 ["source","sh",subs="attributes"]
 ----------------------------------------------------------------
 bin/logstash-keystore create
 ----------------------------------------------------------------
 
-Creates the keystore in the directory defined by the `path.settings`
-configuration setting.
+Creates the keystore in the directory defined in the `path.settings` setting.
 
-NOTE: It is recommended that you set a <<keystore-password,keystore password>>
-when creating the keystore.
+IMPORTANT: If a keystore already exists, the `create` command can overwrite it (after a Y/N prompt).
+Selecting `Y` clears all keys and secrets that were previously stored.  
 
-[float]
+TIP: Set a <<keystore-password,keystore password>> when you create the keystore.
+
+[discrete]
 [[add-keys-to-keystore]]
 === Add keys
 
@@ -147,7 +159,7 @@ bin/logstash-keystore add ES_PWD
 
 When prompted, enter a value for the key.
 
-[float]
+[discrete]
 [[list-settings]]
 === List keys
 
@@ -158,7 +170,7 @@ To list the keys defined in the keystore, use:
 bin/logstash-keystore list
 ----------------------------------------------------------------
 
-[float]
+[discrete]
 [[remove-settings]]
 === Remove keys