From a578beaff5cbd1e39e3ac3fa662d1edaa1eb9817 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Thu, 18 Nov 2021 11:41:56 -0500 Subject: [PATCH] [DOCS] Update Kibana install docs for security ON by default Beta (#118770) * [DOCS] Update install docs for security ON by default * Incorporating reviewer feedback and expanding RPM + Debian steps * Update Debian and RPM enrollment token process --- docs/setup/install/auto-enroll.asciidoc | 21 ++++++++++++++++ docs/setup/install/deb.asciidoc | 24 +++++++++++++++++++ docs/setup/install/rpm.asciidoc | 24 +++++++++++++++++++ .../install/start-es-and-enroll.asciidoc | 16 +++++++++++++ docs/setup/install/systemd.asciidoc | 8 +++---- docs/setup/install/targz-running.asciidoc | 2 ++ docs/setup/install/targz.asciidoc | 2 ++ docs/setup/install/windows-running.asciidoc | 2 ++ docs/setup/install/windows.asciidoc | 3 +++ 9 files changed, 98 insertions(+), 4 deletions(-) create mode 100644 docs/setup/install/auto-enroll.asciidoc create mode 100644 docs/setup/install/start-es-and-enroll.asciidoc diff --git a/docs/setup/install/auto-enroll.asciidoc b/docs/setup/install/auto-enroll.asciidoc new file mode 100644 index 000000000000..0f9f9e2d8a92 --- /dev/null +++ b/docs/setup/install/auto-enroll.asciidoc @@ -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. +==== \ No newline at end of file diff --git a/docs/setup/install/deb.asciidoc b/docs/setup/install/deb.asciidoc index a22942618520..3f600d7c2bdb 100644 --- a/docs/setup/install/deb.asciidoc +++ b/docs/setup/install/deb.asciidoc @@ -122,6 +122,30 @@ sudo dpkg -i kibana-{version}-amd64.deb endif::[] +[[deb-enroll]] +==== Start {es} and generate an enrollment token for {kib} +++++ +Generate an enrollment token +++++ + +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[] diff --git a/docs/setup/install/rpm.asciidoc b/docs/setup/install/rpm.asciidoc index a87d2f89b6dd..329af9af0ccf 100644 --- a/docs/setup/install/rpm.asciidoc +++ b/docs/setup/install/rpm.asciidoc @@ -115,6 +115,30 @@ sudo rpm --install kibana-{version}-x86_64.rpm endif::[] +[[rpm-enroll]] +==== Start {es} and generate an enrollment token for {kib} +++++ +Generate an enrollment token +++++ + +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[] diff --git a/docs/setup/install/start-es-and-enroll.asciidoc b/docs/setup/install/start-es-and-enroll.asciidoc new file mode 100644 index 000000000000..25541ec4aa99 --- /dev/null +++ b/docs/setup/install/start-es-and-enroll.asciidoc @@ -0,0 +1,16 @@ +==== Start {es} and generate an enrollment token for {kib} +++++ +Generate an enrollment token +++++ + +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. \ No newline at end of file diff --git a/docs/setup/install/systemd.asciidoc b/docs/setup/install/systemd.asciidoc index 6fcb82217aff..125626e31424 100644 --- a/docs/setup/install/systemd.asciidoc +++ b/docs/setup/install/systemd.asciidoc @@ -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] @@ -9,7 +9,7 @@ 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] -------------------------------------------- @@ -17,6 +17,6 @@ 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`. \ No newline at end of file diff --git a/docs/setup/install/targz-running.asciidoc b/docs/setup/install/targz-running.asciidoc index d3813d9811b1..40a2626cdd73 100644 --- a/docs/setup/install/targz-running.asciidoc +++ b/docs/setup/install/targz-running.asciidoc @@ -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[] diff --git a/docs/setup/install/targz.asciidoc b/docs/setup/install/targz.asciidoc index 104ac335b523..d9849811a745 100644 --- a/docs/setup/install/targz.asciidoc +++ b/docs/setup/install/targz.asciidoc @@ -90,6 +90,8 @@ cd kibana-{version}/ <2> endif::[] +[[targz-enroll]] +include::start-es-and-enroll.asciidoc[] [[targz-running]] include::targz-running.asciidoc[] diff --git a/docs/setup/install/windows-running.asciidoc b/docs/setup/install/windows-running.asciidoc index 832284edc8f3..aabde22d66d1 100644 --- a/docs/setup/install/windows-running.asciidoc +++ b/docs/setup/install/windows-running.asciidoc @@ -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[] \ No newline at end of file diff --git a/docs/setup/install/windows.asciidoc b/docs/setup/install/windows.asciidoc index 4138fc1886a6..352a327e6119 100644 --- a/docs/setup/install/windows.asciidoc +++ b/docs/setup/install/windows.asciidoc @@ -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[]