From 14795813b7de89b650861fb53e213f7ce20e9b8f Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Mon, 27 Nov 2023 16:11:31 -0600 Subject: [PATCH 1/4] 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 + +++++ +Secrets keystore +++++ + +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 <> 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[] From d4e92123a827b6b09111d53673ecb6d48d8602fa Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Mon, 27 Nov 2023 16:19:47 -0600 Subject: [PATCH 2/4] restore keystore section in command reference --- docs/command-reference.asciidoc | 63 +++++++++++++++++++++++++++++++++ docs/keystore.asciidoc | 4 +-- 2 files changed, 65 insertions(+), 2 deletions(-) diff --git a/docs/command-reference.asciidoc b/docs/command-reference.asciidoc index e8f7df12f42..f3c030ffb4c 100644 --- a/docs/command-reference.asciidoc +++ b/docs/command-reference.asciidoc @@ -34,6 +34,7 @@ ifdef::serverless[] endif::serverless[] :help-command-short-desc: Shows help for any command +:keystore-command-short-desc: Manages the <> :modules-command-short-desc: Manages configured modules :package-command-short-desc: Packages the configuration and executable into a zip file :remove-command-short-desc: Removes the specified function from your serverless environment @@ -106,6 +107,9 @@ ifdef::apm-server[] endif::[] |<> |{export-command-short-desc}. |<> |{help-command-short-desc}. +ifndef::serverless[] +|<> |{keystore-command-short-desc}. +endif::[] ifeval::["{beatname_lc}"=="functionbeat"] |<> |{package-command-short-desc}. |<> |{remove-command-short-desc}. @@ -430,6 +434,65 @@ Specifies the name of the command to show help for. {beatname_lc} help export ----- +ifndef::serverless[] +[float] +[[keystore-command]] +==== `keystore` command + +{keystore-command-short-desc}. + +*SYNOPSIS* + +["source","sh",subs="attributes"] +---- +{beatname_lc} keystore SUBCOMMAND [FLAGS] +---- + +*`SUBCOMMAND`* + +*`add KEY`*:: +Adds the specified key to the keystore. Use the `--force` flag to overwrite an +existing key. Use the `--stdin` flag to pass the value through `stdin`. + +*`create`*:: +Creates a keystore to hold secrets. Use the `--force` flag to overwrite the +existing keystore. + +*`list`*:: +Lists the keys in the keystore. + +*`remove KEY`*:: +Removes the specified key from the keystore. + +*FLAGS* + +*`--force`*:: +Valid with the `add` and `create` subcommands. When used with `add`, overwrites +the specified key. When used with `create`, overwrites the keystore. + +*`--stdin`*:: +When used with `add`, uses the stdin as the source of the key's value. + +*`-h, --help`*:: +Shows help for the `keystore` command. + + +{global-flags} + +*EXAMPLES* + +["source","sh",subs="attributes"] +----- +{beatname_lc} keystore create +{beatname_lc} keystore add ES_PWD +{beatname_lc} keystore remove ES_PWD +{beatname_lc} keystore list +----- + +See <> for more examples. + +endif::[] + ifeval::["{beatname_lc}"=="functionbeat"] [float] [[package-command]] diff --git a/docs/keystore.asciidoc b/docs/keystore.asciidoc index 2cd74ddea6a..071f9c928a3 100644 --- a/docs/keystore.asciidoc +++ b/docs/keystore.asciidoc @@ -35,8 +35,8 @@ 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 <> for the full command syntax, -// including optional flags. +See the <> for the full command syntax, +including optional flags. NOTE: The `keystore` command must be run by the same user who will run APM Server. From d1a3dea069fa212788d960b226976ccace16d305 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Mon, 27 Nov 2023 16:33:32 -0600 Subject: [PATCH 3/4] add new advanced settings pages to list --- docs/setting-up-and-running.asciidoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/setting-up-and-running.asciidoc b/docs/setting-up-and-running.asciidoc index 057ae4c7c2e..18c44af495f 100644 --- a/docs/setting-up-and-running.asciidoc +++ b/docs/setting-up-and-running.asciidoc @@ -12,7 +12,9 @@ for basic installation and running instructions. This section includes additional information on how to set up and run APM Server, including: * <> +* <> * <> +* <> * <> * <> From 8e3a1b3498daf327108ad74b668947b848c06a08 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Tue, 28 Nov 2023 10:16:09 -0600 Subject: [PATCH 4/4] add a note --- docs/keystore.asciidoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/keystore.asciidoc b/docs/keystore.asciidoc index 071f9c928a3..06822a4af1a 100644 --- a/docs/keystore.asciidoc +++ b/docs/keystore.asciidoc @@ -5,6 +5,8 @@ Secrets keystore ++++ +IMPORTANT: The APM Server keystore only applies to the APM Server binary installation method. + 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