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.

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

Confusing steps in internode TLS setup docs #65245

Closed
tvernum opened this issue Nov 19, 2020 · 5 comments · Fixed by #65326
Closed

Confusing steps in internode TLS setup docs #65245

tvernum opened this issue Nov 19, 2020 · 5 comments · Fixed by #65326
Assignees
Labels
>docs General docs changes :Security/TLS SSL/TLS, Certificates Team:Docs Meta label for docs team Team:Security Meta label for security team

Comments

@tvernum
Copy link
Contributor

tvernum commented Nov 19, 2020

In https://www.elastic.co/guide/en/elasticsearch/reference/current/configuring-tls.html we have:

  1. Copy the node certificate to the appropriate locations.

a. Create a folder in the configuration directory on each Elasticsearch node to contain your security certificates. For example, create a certs folder in the /home/es/config/certs directory.

The Elasticsearch configuration directory varies depending on your Elasticsearch installation.

b. Copy the node certificates into the certs directory that you created in the previous step.
c. Copy the .p12 keystore file into the Elasticsearch configuration directory. Elasticsearch will fail to start if the keystore file is located anywhere except this directory.
d. For each additional Elastic product that you want to configure, copy the certificates to the relevant configuration directory.

It looks like this exact wording was introduced in #63334 when we copied some wording from one section to another, but it doesn't quite land right here.

Steps (b) and (c) are saying more or less the same thing with different words. That can confuse the reader because they assume (c) is asking them to do something additional, but they can't work out what it is.
I suspect (b) is intended to cover node certificates (from step 2) and (c) is intended to cover the HTTP certificate store (from step 3), but that's not clear. Perhaps the solution is to explicitly refer to those steps? Something like:

b. On each node, copy the certificates that you created in step 2, into the certs directory that you created in the previous step. This will typically be a single ".p12" (PKCS#12) file

c. If you chose to generate HTTP certificates (step 3), then copy the http.p12 file into the certs directory as well.

_I don't like using "typically" in (b), but going into more explanation is hard, and I'm trying to avoid making big changes, since I know @lockewritesdocs is working on an full overhaul of these instructions.

@tvernum tvernum added >docs General docs changes :Security/TLS SSL/TLS, Certificates labels Nov 19, 2020
@elasticmachine elasticmachine added Team:Security Meta label for security team Team:Docs Meta label for docs team labels Nov 19, 2020
@elasticmachine
Copy link
Collaborator

Pinging @elastic/es-security (Team:Security)

@elasticmachine
Copy link
Collaborator

Pinging @elastic/es-docs (Team:Docs)

@lockewritesdocs
Copy link
Contributor

These instructions are really inadequate. Users need to generate HTTP certs for both Elasticsearch and Kibana, and we glaze over so many of those details. I'm rectifying those omissions in the rewritten security docs, but we should at least patch these instructions until then. I'll open a PR with changes to provide greater clarity for now.

@innocenta55
Copy link

Update security

@innocenta55
Copy link

Upgrade security settings javamachine

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
>docs General docs changes :Security/TLS SSL/TLS, Certificates Team:Docs Meta label for docs team Team:Security Meta label for security team
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants