From 600f0ba2203b017961c12921fb7c0867b476d51f Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Thu, 12 Aug 2021 08:11:30 -0400 Subject: [PATCH] [DOCS] Clarify where to complete security steps (#76120) * [DOCS] Clarify where to complete security steps * Remove config/ from HTTP keystore path * Clarify the node where generating certs for the HTTP layer --- .../security-basic-setup-https.asciidoc | 51 ++++++++++--------- .../security-basic-setup.asciidoc | 18 ++++--- .../security-minimal-setup.asciidoc | 16 +++--- 3 files changed, 47 insertions(+), 38 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/security-basic-setup-https.asciidoc b/x-pack/docs/en/security/securing-communications/security-basic-setup-https.asciidoc index 25da1b44604c6..19892320ccc18 100644 --- a/x-pack/docs/en/security/securing-communications/security-basic-setup-https.asciidoc +++ b/x-pack/docs/en/security/securing-communications/security-basic-setup-https.asciidoc @@ -50,9 +50,9 @@ Complete all steps in <> @@ -155,18 +157,18 @@ created a `/kibana` directory containing an `elasticsearch-ca.pem` file. You use this file to configure {kib} to trust the {es} CA for the HTTP layer. -1. Copy the `elasticsearch-ca.pem` file to the {kib} configuration directory, -as defined by the `KBN_PATH_CONF` path. +. Copy the `elasticsearch-ca.pem` file to the {kib} configuration directory, +as defined by the `$KBN_PATH_CONF` path. -2. Open `kibana.yml` and add the following line to specify the location of the +. Open `kibana.yml` and add the following line to specify the location of the security certificate for the HTTP layer. + [source,yaml] ---- -elasticsearch.ssl.certificateAuthorities: KBN_PATH_CONF/elasticsearch-ca.pem +elasticsearch.ssl.certificateAuthorities: $KBN_PATH_CONF/elasticsearch-ca.pem ---- -3. Add the following line to specify the HTTPS URL for your {es} +. Add the following line to specify the HTTPS URL for your {es} cluster. + [source,yaml] @@ -174,7 +176,7 @@ cluster. elasticsearch.hosts: https://:9200 ---- -4. Restart {kib}. +. Restart {kib}. .Connect to a secure monitoring cluster **** @@ -247,13 +249,13 @@ the server certificate and unencrypted private key. + [source,yaml] ---- -server.ssl.certificate: KBN_PATH_CONF/kibana-server.crt -server.ssl.key: KBN_PATH_CONF/kibana-server.key +server.ssl.certificate: $KBN_PATH_CONF/kibana-server.crt +server.ssl.key: $KBN_PATH_CONF/kibana-server.key ---- + -NOTE: `KBN_PATH_CONF` contains the path for the {kib} configuration files. If +NOTE: `$KBN_PATH_CONF` contains the path for the {kib} configuration files. If you installed {kib} using archive distributions (`zip` or `tar.gz`), the -path defaults to `KBN_HOME/config`. If you used package distributions +path defaults to `$KBN_HOME/config`. If you used package distributions (Debian or RPM), the path defaults to `/etc/kibana`. . Add the following line to `kibana.yml` to enable TLS for inbound @@ -487,8 +489,9 @@ separate monitoring cluster prevents production cluster outages from impacting your ability to access your monitoring data. It also prevents monitoring activities from impacting the performance of your production cluster. -. From the directory where you installed Elasticsearch, navigate to the -`/kibana` directory that you created when <>. +. On the node where you +<>, +navigate to the `/kibana` directory. . Copy the `elasticsearch-ca.pem` certificate to the directory where you installed {metricbeat}. @@ -510,13 +513,13 @@ output.elasticsearch: verification_mode: "certificate" ---- - `hosts`:: Specifies the host where your Elasticsearch cluster is running. + `hosts`:: Specifies the host where your {es} cluster is running. - `protocol`:: Indicates the protocol to use when connecting to Elasticsearch. + `protocol`:: Indicates the protocol to use when connecting to {es}. This value must be `https`. `username`:: Name of the user with privileges required to publish events to - Elasticsearch. The `metricbeat_writer` user that you created has these + {es}. The `metricbeat_writer` user that you created has these privileges. `password`:: Password for the indicated `username`. @@ -592,7 +595,7 @@ See {metricbeat-ref}/configuration-ssl.html[Configure SSL for {metricbeat}]. ./metricbeat setup -e ---- -. Start Elasticsearch, and then start Metricbeat. +. Start {es}, and then start Metricbeat. + [source,shell] ---- @@ -604,4 +607,4 @@ log output. . Log in to Kibana, open the main menu, and click **Stack Monitoring**. + -You’ll see cluster alerts that require your attention and a summary of the available monitoring metrics for Elasticsearch. Click any of the header links on the available cards to view additional information. +You’ll see cluster alerts that require your attention and a summary of the available monitoring metrics for {es}. Click any of the header links on the available cards to view additional information. diff --git a/x-pack/docs/en/security/securing-communications/security-basic-setup.asciidoc b/x-pack/docs/en/security/securing-communications/security-basic-setup.asciidoc index 49936723af816..356d80ede2e13 100644 --- a/x-pack/docs/en/security/securing-communications/security-basic-setup.asciidoc +++ b/x-pack/docs/en/security/securing-communications/security-basic-setup.asciidoc @@ -72,7 +72,8 @@ For the transport layer, we recommend using a separate, dedicated CA instead of an existing, possibly shared CA so that node membership is tightly controlled. Use the `elasticsearch-certutil` tool to generate a CA for your cluster. -. Use the `elasticsearch-certutil` tool to generate a CA for your cluster. +. On any single node, use the `elasticsearch-certutil` tool to generate a CA for +your cluster. + [source,shell] ---- @@ -84,8 +85,9 @@ generate a CA for your cluster. b. Enter a password for your CA. You can choose to leave the password blank if you're not deploying to a production environment. -. Generate a certificate and private key for your node. You include the - `elastic-stack-ca.p12` output file that you generated in the previous step. +. On any single node, generate a certificate and private key for the nodes in +your cluster. You include the `elastic-stack-ca.p12` output file that you +generated in the previous step. + [source,shell] ---- @@ -103,8 +105,8 @@ generate a CA for your cluster. The output file is a keystore named `elastic-certificates.p12`. This file contains a node certificate, node key, and CA certificate. -. Copy the `elastic-certificates.p12` file to the `ES_PATH_CONF` - directory on every node in your cluster. +. On *every* node in your cluster, copy the `elastic-certificates.p12` file to +the `$ES_PATH_CONF` directory. [[encrypt-internode-communication]] ==== Encrypt internode communications with TLS @@ -126,7 +128,7 @@ changes at a frequency determined by the global {es} Complete the following steps *for each node in your cluster*. To join the same cluster, all nodes must share the same `cluster.name` value. -. Open the `ES_PATH_CONF/elasticsearch.yml` file and make the following +. Open the `$ES_PATH_CONF/elasticsearch.yml` file and make the following changes: a. Add the <> setting and enter a name for your cluster: @@ -179,7 +181,9 @@ matches the DNS or IP address. See the . Complete the previous steps for each node in your cluster. -. Restart {es}. The method for <> and <> {es} varies depending on how you installed it. +. On *every* node in your cluster, restart {es}. The method for +<> and <> {es} +varies depending on how you installed it. + For example, if you installed {es} with an archive distribution (`tar.gz` or `.zip`), you can enter `Ctrl+C` on the command line to stop diff --git a/x-pack/docs/en/security/securing-communications/security-minimal-setup.asciidoc b/x-pack/docs/en/security/securing-communications/security-minimal-setup.asciidoc index bae87594dd082..48762316446d5 100644 --- a/x-pack/docs/en/security/securing-communications/security-minimal-setup.asciidoc +++ b/x-pack/docs/en/security/securing-communications/security-minimal-setup.asciidoc @@ -28,22 +28,23 @@ When you use the basic license, the {es} security features are disabled by default. Enabling the {es} security features enables basic authentication so that you can run a local cluster with username and password authentication. -. Stop both {kib} and {es} if they are running. +. On *every* node in your cluster, stop both {kib} and {es} if they are running. -. Add the `xpack.security.enabled` setting to the `ES_PATH_CONF/elasticsearch.yml` file and set the value to `true`: +. On *every* node in your cluster, add the `xpack.security.enabled` setting to +the `$ES_PATH_CONF/elasticsearch.yml` file and set the value to `true`: + [source,yaml] ---- xpack.security.enabled: true ---- + -NOTE: The `ES_PATH_CONF` variable is the path for the {es} +NOTE: The `$ES_PATH_CONF` variable is the path for the {es} configuration files. If you installed {es} using archive distributions -(`zip` or `tar.gz`), the variable defaults to `ES_HOME/config`. If you used +(`zip` or `tar.gz`), the variable defaults to `$ES_HOME/config`. If you used package distributions (Debian or RPM), the variable defaults to `/etc/elasticsearch`. . If your cluster has a single node, add the `discovery.type` setting in the -`ES_PATH_CONF/elasticsearch.yml` file and set the value to `single-node`. This +`$ES_PATH_CONF/elasticsearch.yml` file and set the value to `single-node`. This setting ensures that your node does not inadvertently connect to other clusters that might be running on your network. + @@ -62,8 +63,9 @@ user name and password are rejected. NOTE: You only need to set passwords for the `elastic` and `kibana_system` users when enabling minimal or basic security. -. Start {es}. For example, if you installed Elasticsearch with a -`.tar.gz` package, run the following command from the Elasticsearch directory: +. On *every* node in your cluster, start {es}. For example, if you installed +{es} with a `.tar.gz` package, run the following command from the `ES_HOME` +directory: + [source,shell] ----