diff --git a/docs/en/commands/syskeygen.asciidoc b/docs/en/commands/syskeygen.asciidoc index be8708ecd37..fd4c9235f74 100644 --- a/docs/en/commands/syskeygen.asciidoc +++ b/docs/en/commands/syskeygen.asciidoc @@ -2,15 +2,7 @@ [[syskeygen]] == syskeygen -The `syskeygen` command creates a system key file in -`CONFIG_DIR/x-pack/system_key`. You can then copy the generated system key to -the rest of the nodes in the cluster. - -//TBD: Why? What's its purpose? - -IMPORTANT: The system key is a symmetric key, so the same key must be on every -node in the cluster. You must also ensure that the file permissions are set -such that the key can be read by the user that {es} runs as. +The `syskeygen` command creates a system key file in `CONFIG_DIR/x-pack`. [float] === Synopsis @@ -25,21 +17,19 @@ bin/x-pack/syskeygen [float] === Description -Encryption of sensitive data requires a key. For example, if you enable the -<>, -//TBD: Can we clarify what type of sensitive data is encrypted when this is enabled? -you must also create a system key file and place it in the secure setting store. -After you run the `syskeygen` command, run the -`elasticsearch-keystore add-file xpack.watcher.encryption_key ` -command. Finally, remove the `system_key` file from the filesystem. Repeat these -steps on every node in the cluster. +The command generates a `system_key` file, which you can use to symmetrically +encrypt sensitive data. For example, you can use this key to prevent {watcher} +from returning and storing information that contains clear text credentials. See {xpack-ref}/encrypting-data.html[Encrypting sensitive data in {watcher}]. -//TBD: Are there other scenarios where you could use this system file? +IMPORTANT: The system key is a symmetric key, so the same key must be used on +every node in the cluster. [float] === Parameters -`-E `:: Configures a setting. +`-E `:: Configures a setting. For example, if you have a custom +installation of {es}, you can use this parameter to specify the `ES_PATH_CONF` +environment variable. `-h, --help`:: Returns all of the command parameters. @@ -47,14 +37,14 @@ steps on every node in the cluster. `-v, --verbose`:: Shows verbose output. -//// + [float] === Examples -//TBD: What's an example of a -E value that we might use in this command? +The following command generates a `system_key` file in the +default `$ES_HOME/config/x-pack` directory: [source, sh] -------------------------------------------------- bin/x-pack/syskeygen -------------------------------------------------- -//// diff --git a/docs/en/settings/notification-settings.asciidoc b/docs/en/settings/notification-settings.asciidoc index 65d536e7e7c..2784aa88b80 100644 --- a/docs/en/settings/notification-settings.asciidoc +++ b/docs/en/settings/notification-settings.asciidoc @@ -24,17 +24,15 @@ Set to `false` to disable {watcher} on the node. `xpack.watcher.encrypt_sensitive_data` (<>):: Set to `true` to encrypt sensitive data. If this setting is enabled, you -must also specify the `xpack.watcher.encryption_key` setting. -//TBD: Can we be more specific about what type of watcher data it's encrypting? +must also specify the `xpack.watcher.encryption_key` setting. For more +information, see +{xpack-ref}/encrypting-data.html[Encrypting sensitive data in {watcher}]. `xpack.watcher.encryption_key` (<>):: Specifies the path to a file that contains a key for encrypting sensitive data. If `xpack.watcher.encrypt_sensitive_data` is set to `true`, this setting is -required. For example, to generate the key file, run the <> tool. -Then import the key into the secure setting store with the -`elasticsearch-keystore add-file xpack.watcher.encryption_key ` -command. Finally, remove the system_key file from the filesystem. Repeat this on -every node in the cluster. +required. For more information, see +{xpack-ref}/encrypting-data.html[Encrypting sensitive data in {watcher}]. `xpack.watcher.history.cleaner_service.enabled`:: Set to `false` (default) to disable the cleaner service, which removes previous diff --git a/docs/en/watcher/encrypting-data.asciidoc b/docs/en/watcher/encrypting-data.asciidoc new file mode 100644 index 00000000000..5f2a55ac6a7 --- /dev/null +++ b/docs/en/watcher/encrypting-data.asciidoc @@ -0,0 +1,53 @@ +[[encrypting-data]] +== Encrypting Sensitive Data in {watcher} + +Watches might have access to sensitive data such as HTTP basic authentication +information or details about your SMTP email service. You can encrypt this +data by generating a key and adding some secure settings on each node in your +cluster. + +To encrypt sensitive data in {watcher}: + +. Use the {ref}/syskeygen.html[syskeygen] command to create a system key file. + +. Copy the `system_key` file to all of the nodes in your cluster. ++ +-- +IMPORTANT: The system key is a symmetric key, so the same key must be used on +every node in the cluster. + +-- + +. Set the +{ref}/notification-settings.html[`xpack.watcher.encrypt_sensitive_data` setting] +in the {ref}/secure-settings.html[{es} keystore] on each node in the cluster. ++ +-- + +For example, run the following commands to create and update the keystore: + +[source,sh] +---------------------------------------------------------------- +bin/elasticsearch-keystore create +bin/elasticsearch-keystore add xpack.watcher.encrypt_sensitive_data true +---------------------------------------------------------------- +-- + +. Set the +{ref}/notification-settings.html[`xpack.watcher.encryption_key` setting] in the +{ref}/secure-settings.html[{es} keystore] on each node in the cluster. ++ +-- +For example, run the following command to import the `system_key` file on +each node: + +[source,sh] +---------------------------------------------------------------- +bin/elasticsearch-keystore add-file xpack.watcher.encryption_key /system_key +---------------------------------------------------------------- +-- + +. Delete the `system_key` file on each node in the cluster. + +NOTE: Existing watches are not affected by these changes. Only watches that you +create after following these steps have encryption enabled. diff --git a/docs/en/watcher/index.asciidoc b/docs/en/watcher/index.asciidoc index 65e5be0d468..0fa92675f4b 100644 --- a/docs/en/watcher/index.asciidoc +++ b/docs/en/watcher/index.asciidoc @@ -74,6 +74,8 @@ include::getting-started.asciidoc[] include::how-watcher-works.asciidoc[] +include::encrypting-data.asciidoc[] + include::input.asciidoc[] include::trigger.asciidoc[]