Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[7.14] [DOCS] Clarify where to complete security steps #76120

Merged
merged 3 commits into from
Aug 12, 2021
+47 −38
Merged

[7.14] [DOCS] Clarify where to complete security steps #76120

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
31c8a79
[DOCS] Clarify where to complete security steps
Aug 4, 2021
344ed67
Remove config/ from HTTP keystore path
Aug 5, 2021
051ea8f
Clarify the node where generating certs for the HTTP layer
Aug 11, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 27 additions & 25 deletions ...ck/docs/en/security/securing-communications/security-basic-setup-https.asciidoc
View file
Open in desktop
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
xpack.security.http.ssl.keystore.path: config/http.p12
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The config/ part is not needed. Configuration files are resolved relative to the config directory.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @ywangd -- I'll remove config/ from the path.

----

. 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>.com: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 @@ -486,8 +488,8 @@ 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 any single node, navigate to the `/kibana` directory that you created when
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be On the node on which you generated the HTTP certificates ? (or neater wording to that effect)

I don't think we would assume that they copied the kibana directory to every node (though they might have)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good eye @tvernum 👀

I'll change this to read:

. On the node where you <<encrypt-http-communication,generated certificates for the HTTP layer>>, navigate to the /kibana directory.

<<encrypt-http-communication,encrypting HTTP client communications for {es}>>.

. Copy the `elasticsearch-ca.pem` certificate to the directory where you
installed {metricbeat}.
Expand All @@ -509,13 +511,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 @@ -591,7 +593,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 @@ -603,4 +605,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.
18 changes: 11 additions & 7 deletions x-pack/docs/en/security/securing-communications/security-basic-setup.asciidoc
View file
Open in desktop
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
16 changes: 9 additions & 7 deletions x-pack/docs/en/security/securing-communications/security-minimal-setup.asciidoc
View file
Open in desktop
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