Skip to content

Commit

Permalink
[DOCS] Update Kibana install docs for security ON by default Beta (#1…
Browse files Browse the repository at this point in the history
…18770)

* [DOCS] Update install docs for security ON by default

* Incorporating reviewer feedback and expanding RPM + Debian steps

* Update Debian and RPM enrollment token process
  • Loading branch information
Adam Locke authored Nov 18, 2021
1 parent 617be51 commit a578bea
Show file tree
Hide file tree
Showing 9 changed files with 98 additions and 4 deletions.
21 changes: 21 additions & 0 deletions docs/setup/install/auto-enroll.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
[role="exclude"]

If this is the first time you're starting {kib}, this command generates a
unique link in your terminal to enroll your {kib} instance with {es}.

. In your terminal, click the generated link to open {kib} in your browser.

. In your browser, paste the enrollment token that was generated in the terminal
when you started {es}, and then click the button to connect your {kib} instance with {es}.

. Log in to {kib} as the `elastic` user with the password that was
generated when you started {es}.

[NOTE]
====
If you need to reset the password for the `elastic` user or other
built-in users, run the {ref}/reset-password.html[`elasticsearch-reset-password`] tool. To generate new enrollment tokens for
{kib} or {es} nodes, run the
{ref}/create-enrollment-token.html[`elasticsearch-create-enrollment-token`] tool.
These tools are available in the {es} `bin` directory.
====
24 changes: 24 additions & 0 deletions docs/setup/install/deb.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,30 @@ sudo dpkg -i kibana-{version}-amd64.deb

endif::[]

[[deb-enroll]]
==== Start {es} and generate an enrollment token for {kib}
++++
<titleabbrev>Generate an enrollment token</titleabbrev>
++++

When you start {es} for the first time, the following security configuration
occurs automatically:

* Authentication and authorization are enabled, and a password is generated for the `elastic` built-in superuser.
* Certificates and keys for TLS are generated for the transport and HTTP layer, and TLS is enabled and configured with these keys and certificates.

The password and certificate and keys are output to your terminal.

You can then generate an enrollment token for {kib} with the
{ref}/create-enrollment-token.html[`elasticsearch-create-enrollment-token`] tool:

[source,sh]
----
bin/elasticsearch-create-enrollment-token -s kibana
----

Start {kib} and enter the enrollment token to securely connect {kib} with {es}.

[[deb-running-systemd]]
include::systemd.asciidoc[]

Expand Down
24 changes: 24 additions & 0 deletions docs/setup/install/rpm.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,30 @@ sudo rpm --install kibana-{version}-x86_64.rpm

endif::[]

[[rpm-enroll]]
==== Start {es} and generate an enrollment token for {kib}
++++
<titleabbrev>Generate an enrollment token</titleabbrev>
++++

When you start {es} for the first time, the following security configuration
occurs automatically:

* Authentication and authorization are enabled, and a password is generated for the `elastic` built-in superuser.
* Certificates and keys for TLS are generated for the transport and HTTP layer, and TLS is enabled and configured with these keys and certificates.

The password and certificate and keys are output to your terminal.

You can then generate an enrollment token for {kib} with the
{ref}/create-enrollment-token.html[`elasticsearch-create-enrollment-token`] tool:

[source,sh]
----
bin/elasticsearch-create-enrollment-token -s kibana
----

Start {kib} and enter the enrollment token to securely connect {kib} with {es}.

[[rpm-running-systemd]]
include::systemd.asciidoc[]

Expand Down
16 changes: 16 additions & 0 deletions docs/setup/install/start-es-and-enroll.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
==== Start {es} and generate an enrollment token for {kib}
++++
<titleabbrev>Generate an enrollment token</titleabbrev>
++++

When you start {es} for the first time, the following security configuration
occurs automatically:

* {ref}/configuring-stack-security.html#stack-security-certificates[Certificates and keys] for TLS are
generated for the transport and HTTP layers.
* The TLS configuration settings are written to `elasticsearch.yml`.
* A password is generated for the `elastic` user.
* An enrollment token is generated for {kib}.
You can then start {kib} and enter the enrollment token to securely connect
{kib} with {es}. The enrollment token is valid for 30 minutes.
8 changes: 4 additions & 4 deletions docs/setup/install/systemd.asciidoc
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
==== Run {kib} with `systemd`

To configure Kibana to start automatically when the system boots up,
To configure {kib} to start automatically when the system starts,
run the following commands:

[source,sh]
Expand All @@ -9,14 +9,14 @@ sudo /bin/systemctl daemon-reload
sudo /bin/systemctl enable kibana.service
--------------------------------------------------

Kibana can be started and stopped as follows:
{kib} can be started and stopped as follows:

[source,sh]
--------------------------------------------
sudo systemctl start kibana.service
sudo systemctl stop kibana.service
--------------------------------------------

These commands provide no feedback as to whether Kibana was started
These commands provide no feedback as to whether {kib} was started
successfully or not. Log information can be accessed via
`journalctl -u kibana.service`.
`journalctl -u kibana.service`.
2 changes: 2 additions & 0 deletions docs/setup/install/targz-running.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,5 @@ Kibana can be started from the command line as follows:

By default, Kibana runs in the foreground, prints its logs to the
standard output (`stdout`), and can be stopped by pressing *Ctrl-C*.

include::auto-enroll.asciidoc[]
2 changes: 2 additions & 0 deletions docs/setup/install/targz.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,8 @@ cd kibana-{version}/ <2>

endif::[]

[[targz-enroll]]
include::start-es-and-enroll.asciidoc[]

[[targz-running]]
include::targz-running.asciidoc[]
Expand Down
2 changes: 2 additions & 0 deletions docs/setup/install/windows-running.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,5 @@ Kibana can be started from the command line as follows:

By default, Kibana runs in the foreground, prints its logs to `STDOUT`,
and can be stopped by pressing *Ctrl-C*.

include::auto-enroll.asciidoc[]
3 changes: 3 additions & 0 deletions docs/setup/install/windows.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,9 @@ CD c:\kibana-{version}-windows-x86_64

endif::[]

[[windows-enroll]]
include::start-es-and-enroll.asciidoc[]

[[windows-running]]
include::windows-running.asciidoc[]

Expand Down

0 comments on commit a578bea

Please sign in to comment.