[DOCS] Adds elasticsearch-keystore command reference (#50872)

docs/reference/commands/index.asciidoc

@@ -10,6 +10,7 @@ tasks from the command line:
 * <<certgen>>
 * <<certutil>>
 * <<elasticsearch-croneval>>
+* <<elasticsearch-keystore>>
 * <<migrate-tool>>
 * <<node-tool>>
 * <<saml-metadata>>
@@ -23,6 +24,7 @@ tasks from the command line:
 include::certgen.asciidoc[]
 include::certutil.asciidoc[]
 include::croneval.asciidoc[]
+include::keystore.asciidoc[]
 include::migrate-tool.asciidoc[]
 include::node-tool.asciidoc[]
 include::saml-metadata.asciidoc[]

docs/reference/commands/keystore.asciidoc

@@ -0,0 +1,149 @@
+[[elasticsearch-keystore]]
+== elasticsearch-keystore
+
+The `elasticsearch-keystore` command manages <<secure-settings,secure settings>>
+in the {es} keystore.
+
+[discrete]
+[[elasticsearch-keystore-synopsis]]
+=== Synopsis
+
+[source,shell]
+--------------------------------------------------
+bin/elasticsearch-keystore
+([add <setting>] [--stdin] |
+[add-file <setting> <path>] | [create] |
+[list] | [remove <setting>] | [upgrade])
+[-h, --help] ([-s, --silent] | [-v, --verbose])
+--------------------------------------------------
+
+[discrete]
+[[elasticsearch-keystore-description]]
+=== Description
+
+IMPORTANT: This command should be run as the user that will run {es}.
+
+Currently, all secure settings are node-specific settings that must have the
+same value on every node. Therefore you must run this command on every node.
+
+Modifications to the keystore do not take effect until you restart {es}.
+
+Only some settings are designed to be read from the keystore. However, there
+is no validation to block unsupported settings from the keystore and they can
+cause {es} to fail to start. To see whether a setting is supported in the
+keystore, see the setting reference.
+
+[discrete]
+[[elasticsearch-keystore-parameters]]
+=== Parameters
+
+`add <setting>`:: Adds settings to the keystore. By default, you are prompted
+for the value of the setting.
+
+`add-file <setting> <path>`:: Adds a file to the keystore.
+
+`create`:: Creates the keystore.
+
+`-h, --help`:: Returns all of the command parameters.
+
+`list`:: Lists the settings in the keystore.
+
+`remove <setting>:: Removes a setting from the keystore.
+
+`-s, --silent`:: Shows minimal output.
+
+`--stdin`:: When used with the `add` parameter, you can pass the setting value
+through standard input (stdin). See <<add-string-to-keystore>>.
+
+`upgrade`:: Upgrades the internal format of the keystore.
+
+`-v, --verbose`:: Shows verbose output.
+
+[discrete]
+[[elasticsearch-keystore-examples]]
+=== Examples
+
+[discrete]
+[[creating-keystore]]
+==== Create the keystore
+
+To create the `elasticsearch.keystore`, use the `create` command:
+
+[source,sh]
+----------------------------------------------------------------
+bin/elasticsearch-keystore create
+----------------------------------------------------------------
+
+A `elasticsearch.keystore` file is created alongside the `elasticsearch.yml`
+file.
+
+[discrete]
+[[list-settings]]
+==== List settings in the keystore
+
+To list the settings in the keystore, use the `list` command.
+
+[source,sh]
+----------------------------------------------------------------
+bin/elasticsearch-keystore list
+----------------------------------------------------------------
+
+[discrete]
+[[add-string-to-keystore]]
+==== Add settings to the keystore
+
+Sensitive string settings, like authentication credentials for Cloud plugins,
+can be added with the `add` command:
+
+[source,sh]
+----------------------------------------------------------------
+bin/elasticsearch-keystore add the.setting.name.to.set
+----------------------------------------------------------------
+
+You are prompted to enter the value of the setting. To pass the value
+through standard input (stdin), use the `--stdin` flag:
+
+[source,sh]
+----------------------------------------------------------------
+cat /file/containing/setting/value | bin/elasticsearch-keystore add --stdin the.setting.name.to.set
+----------------------------------------------------------------
+
+[discrete]
+[[add-file-to-keystore]]
+==== Add files to the keystore
+
+You can add sensitive files, like authentication key files for Cloud plugins,
+using the `add-file` command. Be sure to include your file path as an argument
+after the setting name.
+
+[source,sh]
+----------------------------------------------------------------
+bin/elasticsearch-keystore add-file the.setting.name.to.set /path/example-file.json
+----------------------------------------------------------------
+
+[discrete]
+[[remove-settings]]
+==== Remove settings from the keystore
+
+To remove a setting from the keystore, use the `remove` command:
+
+[source,sh]
+----------------------------------------------------------------
+bin/elasticsearch-keystore remove the.setting.name.to.remove
+----------------------------------------------------------------
+
+[discrete]
+[[keystore-upgrade]]
+==== Upgrade the keystore
+
+Occasionally, the internal format of the keystore changes. When {es} is
+installed from a package manager, an upgrade of the on-disk keystore to the new
+format is done during package upgrade. In other cases, {es} performs the upgrade
+during node startup. This requires that {es} has write permissions to the
+directory that contains the keystore. Alternatively, you can manually perform
+such an upgrade by using the `upgrade` command:
+
+[source,sh]
+----------------------------------------------------------------
+bin/elasticsearch-keystore upgrade
+----------------------------------------------------------------

docs/reference/setup/secure-settings.asciidoc

@@ -2,120 +2,33 @@
 === Secure settings
 
 Some settings are sensitive, and relying on filesystem permissions to protect
-their values is not sufficient. For this use case, Elasticsearch provides a
-keystore and the `elasticsearch-keystore` tool to manage the settings in the keystore.
-
-NOTE: All commands here should be run as the user which will run Elasticsearch.
+their values is not sufficient. For this use case, {es} provides a
+keystore and the <<elasticsearch-keystore,`elasticsearch-keystore` tool>> to
+manage the settings in the keystore.
 
 IMPORTANT: Only some settings are designed to be read from the keystore. However,
-the keystore has no validation to block unsupported settings.
-Adding unsupported settings to the keystore will cause {es}
-to fail to start. See documentation for each setting to see if it is supported
-as part of the keystore.
+the keystore has no validation to block unsupported settings. Adding unsupported
+settings to the keystore causes {es} to fail to start. To see whether a setting
+is supported in the keystore, look for a "Secure" qualifier the setting
+reference.
 
-NOTE: All the modifications to the keystore take affect only after restarting
-Elasticsearch.
+All the modifications to the keystore take affect only after restarting {es}.
 
-NOTE: The elasticsearch keystore currently only provides obfuscation. In the future,
+NOTE: The {es} keystore currently only provides obfuscation. In the future,
 password protection will be added.
 
 These settings, just like the regular ones in the `elasticsearch.yml` config file,
 need to be specified on each node in the cluster. Currently, all secure settings
 are node-specific settings that must have the same value on every node.
 
-[float]
-[[creating-keystore]]
-=== Creating the keystore
-
-To create the `elasticsearch.keystore`, use the `create` command:
-
-[source,sh]
-----------------------------------------------------------------
-bin/elasticsearch-keystore create
-----------------------------------------------------------------
-
-The file `elasticsearch.keystore` will be created alongside `elasticsearch.yml`.
-
-[float]
-[[list-settings]]
-=== Listing settings in the keystore
-
-A list of the settings in the keystore is available with the `list` command:
-
-[source,sh]
-----------------------------------------------------------------
-bin/elasticsearch-keystore list
-----------------------------------------------------------------
-
-[float]
-[[add-string-to-keystore]]
-=== Adding string settings
-
-Sensitive string settings, like authentication credentials for cloud
-plugins, can be added using the `add` command:
-
-[source,sh]
-----------------------------------------------------------------
-bin/elasticsearch-keystore add the.setting.name.to.set
-----------------------------------------------------------------
-
-The tool will prompt for the value of the setting. To pass the value
-through stdin, use the `--stdin` flag:
-
-[source,sh]
-----------------------------------------------------------------
-cat /file/containing/setting/value | bin/elasticsearch-keystore add --stdin the.setting.name.to.set
-----------------------------------------------------------------
-
-[float]
-[[add-file-to-keystore]]
-=== Adding file settings
-You can add sensitive files, like authentication key files for cloud plugins,
-using the `add-file` command. Be sure to include your file path as an argument
-after the setting name.
-
-[source,sh]
-----------------------------------------------------------------
-bin/elasticsearch-keystore add-file the.setting.name.to.set /path/example-file.json
-----------------------------------------------------------------
-
-[float]
-[[remove-settings]]
-=== Removing settings
-
-To remove a setting from the keystore, use the `remove` command:
-
-[source,sh]
-----------------------------------------------------------------
-bin/elasticsearch-keystore remove the.setting.name.to.remove
-----------------------------------------------------------------
-
-[float]
-[[keystore-upgrade]]
-=== Upgrading the keystore
-
-Occasionally, the internal format of the keystore changes. When Elasticsearch is
-installed from a package manager, an upgrade of the on-disk keystore to the new
-format is done during package upgrade. In other cases, Elasticsearch will
-perform such an upgrade during node startup. This requires that Elasticsearch
-have write permissions to the directory that contains the keystore.
-Alternatively, you can manually perform such an upgrade by using the `upgrade`
-command:
-
-[source,sh]
-----------------------------------------------------------------
-bin/elasticsearch-keystore upgrade
-----------------------------------------------------------------
-
-[float]
+[discrete]
 [[reloadable-secure-settings]]
 === Reloadable secure settings
 
-Just like the settings values in `elasticsearch.yml`, changes to the
-keystore contents are not automatically applied to the running
-elasticsearch node. Re-reading settings requires a node restart.
-However, certain secure settings are marked as *reloadable*. Such settings
-can be re-read and applied on a running node.
+Just like the settings values in `elasticsearch.yml`, changes to the keystore
+contents are not automatically applied to the running {es} node. Re-reading
+settings requires a node restart. However, certain secure settings are marked as
+*reloadable*. Such settings can be re-read and applied on a running node.
 
 The values of all secure settings, *reloadable* or not, must be identical
 across all cluster nodes. After making the desired secure settings changes,
@@ -126,16 +39,16 @@ using the `bin/elasticsearch-keystore add` command, call:
 POST _nodes/reload_secure_settings
 ----
 
-This API will decrypt and re-read the entire keystore, on every cluster node,
-but only the *reloadable* secure settings will be applied. Changes to other
-settings will not go into effect until the next restart. Once the call returns,
-the reload has been completed, meaning that all internal datastructures dependent
-on these settings have been changed. Everything should look as if the settings
-had the new value from the start.
+This API decrypts and re-reads the entire keystore, on every cluster node,
+but only the *reloadable* secure settings are applied. Changes to other
+settings do not go into effect until the next restart. Once the call returns,
+the reload has been completed, meaning that all internal data structures
+dependent on these settings have been changed. Everything should look as if the
+settings had the new value from the start.
 
-When changing multiple *reloadable* secure settings, modify all of them, on
-each cluster node, and then issue a `reload_secure_settings` call, instead
-of reloading after each modification.
+When changing multiple *reloadable* secure settings, modify all of them on each
+cluster node, then issue a `reload_secure_settings` call instead of reloading
+after each modification.
 
 There are reloadable secure settings for: