Skip to content

Commit

Permalink
[DOCS] Clarify where to complete security steps (elastic#76120)
Browse files Browse the repository at this point in the history
* [DOCS] Clarify where to complete security steps

* Remove config/ from HTTP keystore path

* Clarify the node where generating certs for the HTTP layer
  • Loading branch information
Adam Locke committed Aug 12, 2021
1 parent 2ccad76 commit 600f0ba
Show file tree
Hide file tree
Showing 3 changed files with 47 additions and 38 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,9 @@ Complete all steps in <<security-basic-setup,Set up basic security for the Elast
[[encrypt-http-communication]]
==== Encrypt HTTP client communications for {es}

. Stop {es} and {kib} if they are running.
. On *every* node in your cluster, stop {es} and {kib} if they are running.

. From the directory where you installed {es}, run the {es}
. On any single node, from the directory where you installed {es}, run the {es}
HTTP certificate tool to generate a Certificate Signing Request (CSR).
+
[source,shell]
Expand Down Expand Up @@ -117,25 +117,27 @@ List every hostname and variant used to connect to your cluster over HTTPS.
----
--

. Copy the relevant `http.p12` certificate to the `ES_PATH_CONF` directory on each node.
. On *every* node in your cluster, complete the following steps:

. On each node, edit the `elasticsearch.yml` file to enable HTTPS security and
specify the location of the `http.p12` security certificate.
.. Copy the relevant `http.p12` certificate to the `$ES_PATH_CONF` directory.

.. Edit the `elasticsearch.yml` file to enable HTTPS security and specify the
location of the `http.p12` security certificate.
+
[source,yaml]
----
xpack.security.http.ssl.enabled: true
xpack.security.http.ssl.keystore.path: http.p12
----

. Add the password for your private key to the secure settings in {es}.
.. Add the password for your private key to the secure settings in {es}.
+
[source,shell]
----
./bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password
----

. Start {es}.
.. Start {es}.

**Next**: <<encrypt-kibana-http,Encrypt HTTP client communications for {kib}>>

Expand All @@ -155,26 +157,26 @@ 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]
----
elasticsearch.hosts: https://<your_elasticsearch_host>:9200
----

4. Restart {kib}.
. Restart {kib}.

.Connect to a secure monitoring cluster
****
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 <<encrypt-http-communication,encrypting HTTP client communications for {es}>>.
. On the node where you
<<encrypt-http-communication,generated certificates for the HTTP layer>>,
navigate to the `/kibana` directory.

. Copy the `elasticsearch-ca.pem` certificate to the directory where you
installed {metricbeat}.
Expand All @@ -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`.
Expand Down Expand Up @@ -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]
----
Expand All @@ -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.
Original file line number Diff line number Diff line change
Expand Up @@ -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]
----
Expand All @@ -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]
----
Expand All @@ -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
Expand All @@ -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 <<cluster-name,`cluster-name`>> setting and enter a name for your cluster:
Expand Down Expand Up @@ -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 <<starting-elasticsearch,starting>> and <<starting-elasticsearch,stopping>> {es} varies depending on how you installed it.
. On *every* node in your cluster, restart {es}. The method for
<<starting-elasticsearch,starting>> and <<starting-elasticsearch,stopping>> {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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
+
Expand All @@ -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]
----
Expand Down

0 comments on commit 600f0ba

Please sign in to comment.