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

[8.0] [DOCS] Add docs for verifying CA fingerprint (#81279) #81772

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
50 changes: 50 additions & 0 deletions docs/reference/setup/install/connect-clients.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
==== Connect clients to {es}

When you start {es} for the first time, TLS is configured automatically for the
HTTP layer. A CA certificate is generated and stored on disk, and the hex-coded
SHA-256 fingerprint of this certificate is also output to the terminal. Any
clients that connect to {es}, such as the
https://www.elastic.co/guide/en/elasticsearch/client/index.html[{es} Clients],
{beats}, {ls}, and {fleet} must validate that they trust the certificate that
{es} uses for HTTPS. Clients can establish trust by using either the fingerprint
of the CA certificate or the CA certificate itself.

If the auto-configuration process already completed, you can still obtain the
fingerprint of the security certificate. You can also copy the CA certificate
to your machine and configure your client to use it.

[discrete]
===== Use the CA fingerprint

Copy the fingerprint value that's output to your terminal when {es} starts, and
configure your client to use this fingerprint to establish trust when it
connects to {es}.

If the auto-configuration process already completed, you can still obtain the
fingerprint of the security certificate by running the following command. The
path is to the auto-generated CA certificate for the HTTP layer.

[source,sh]
----
openssl x509 -fingerprint -sha256 -in config/tls_auto_config_<timestamp>/http_ca.crt
----

`<timestamp>`:: The timestamp of when the auto-configuration process created the security files directory.

The command returns the security certificate, including the fingerprint.
The `issuer` should be `Elasticsearch security auto-configuration HTTP CA`.

[source,sh]
----
issuer= /CN=Elasticsearch security auto-configuration HTTP CA
SHA256 Fingerprint=<fingerprint>
----

[discrete]
===== Use the CA certificate

If your library doesn't support a method of validating the fingerprint, the
auto-generated CA certificate is created in the
`config/tls_auto_config_<timestamp>` directory on each {es} node. Copy the
`http_ca.crt` file to your machine and configure your client to use this
certificate to establish trust when it connects to {es}.
2 changes: 2 additions & 0 deletions docs/reference/setup/install/deb.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -166,6 +166,8 @@ NOTE: Distributions that use `systemd` require that system resource limits be
configured via `systemd` rather than via the `/etc/sysconfig/elasticsearch`
file. See <<systemd>> for more information.

include::connect-clients.asciidoc[]

[[deb-layout]]
==== Directory layout of Debian package

Expand Down
2 changes: 2 additions & 0 deletions docs/reference/setup/install/rpm.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -159,6 +159,8 @@ NOTE: Distributions that use `systemd` require that system resource limits be
configured via `systemd` rather than via the `/etc/sysconfig/elasticsearch`
file. See <<systemd>> for more information.

include::connect-clients.asciidoc[]

[[rpm-layout]]
==== Directory layout of RPM

Expand Down
2 changes: 2 additions & 0 deletions docs/reference/setup/install/targz.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,8 @@ TIP: Typically, any cluster-wide settings (like `cluster.name`) should be
added to the `elasticsearch.yml` config file, while any node-specific settings
such as `node.name` could be specified on the command line.

include::connect-clients.asciidoc[]

[[targz-layout]]
==== Directory layout of archives

Expand Down
2 changes: 2 additions & 0 deletions docs/reference/setup/install/windows.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -434,6 +434,8 @@ for plugins not currently installed, to be downloaded and installed:
[[msi-installer-upgrade-plugins]]
image::images/msi_installer/msi_installer_upgrade_plugins.png[]

include::connect-clients.asciidoc[]

[[upgrade-msi-command-line]]
==== Upgrade using the command line

Expand Down
2 changes: 2 additions & 0 deletions docs/reference/setup/install/zip-windows.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -256,6 +256,8 @@ It is also possible to configure the service after it's been installed using the

Most changes (like JVM settings) made through the manager GUI will require a restart of the service to take affect.

include::connect-clients.asciidoc[]

[[windows-layout]]
==== Directory layout of `.zip` archive

Expand Down
3 changes: 3 additions & 0 deletions x-pack/docs/en/security/configuring-stack-security.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,9 @@ when you started {es}.

include::enroll-nodes.asciidoc[]

[discrete]
include::{es-ref-dir}/setup/install/connect-clients.asciidoc[leveloffset=-1]

[discrete]
=== What's next?
Congratulations! You've successfully started the {stack} with security enabled.
Expand Down