Browse Source

[DOCS] Update archive install docs for security ON by default (#80375)

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

* Remove extra attribute references that aren't needed

* Incorporate security info into start page

* Update heading
Adam Locke 4 years ago
parent
commit
b13df02d83

+ 3 - 3
docs/reference/setup/install/check-running.asciidoc

@@ -1,11 +1,11 @@
-==== Checking that Elasticsearch is running
+==== Check that Elasticsearch is running
 
 You can test that your {es} node is running by sending an HTTPS request to port
 `9200` on `localhost`:
 
-[source,shell]
+["source","sh",subs="attributes"]
 ----
-curl --cacert /etc/elasticsearch/tls_auto_config_<timestamp>/http_ca.crt \
+curl --cacert {os-dir}/tls_auto_config_<timestamp>/http_ca.crt \
 -u elastic https://localhost:9200 <1>
 ----
 // NOTCONSOLE

+ 3 - 0
docs/reference/setup/install/deb.asciidoc

@@ -146,6 +146,9 @@ endif::include-xpack[]
 include::systemd.asciidoc[]
 
 [[deb-check-running]]
+
+:os-dir:       /etc/elasticsearch
+
 include::check-running.asciidoc[]
 
 [[deb-configuring]]

+ 3 - 0
docs/reference/setup/install/rpm.asciidoc

@@ -139,6 +139,9 @@ endif::include-xpack[]
 include::systemd.asciidoc[]
 
 [[rpm-check-running]]
+
+:os-dir:       /etc/elasticsearch
+
 include::check-running.asciidoc[]
 
 [[rpm-configuring]]

+ 3 - 3
docs/reference/setup/install/security-files-reference.asciidoc

@@ -2,9 +2,9 @@
 ===== Security certificates and keys
 
 When you install {es}, the following certificates and keys are
-generated in the `/etc/elasticsearch/tls_auto_config_<timestamp>` directory,
-which are used to connect a {kib} instance to your secured {es} cluster and
-to encrypt internode communication. The files are listed here for reference.
+generated in the {es} configuration directory, which are used to connect a {kib}
+instance to your secured {es} cluster and to encrypt internode communication.
+The files are listed here for reference.
 
 `http_ca.crt`::
 The CA certificate that is used to sign the certificates for the HTTP layer of

+ 1 - 1
docs/reference/setup/install/targz-daemon.asciidoc

@@ -1,4 +1,4 @@
-==== Running as a daemon
+==== Run as a daemon
 
 To run Elasticsearch as a daemon, specify `-d` on the command line, and record
 the process ID in a file using the `-p` option:

+ 46 - 7
docs/reference/setup/install/targz-start.asciidoc

@@ -1,11 +1,46 @@
-==== Running Elasticsearch from the command line
+==== Run {es} from the command line
 
-Elasticsearch can be started from the command line as follows:
+Run the following command to start {es} from the command line:
 
 [source,sh]
---------------------------------------------
+----
 ./bin/elasticsearch
---------------------------------------------
+----
+
+When starting {es} for the first time, security features are enabled and
+configured by default. 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.
+* An enrollment token is generated for {kib}, which is valid for 30 minutes.
+
+The password for the `elastic` user and the enrollment token for {kib} are
+output to your terminal. For example:
+
+[source,sh]
+----
+The generated password for the elastic built-in superuser is:
+H16Wd=K4dcmgZVA-GE2I
+
+The enrollment token for Kibana instances, valid for the next 30 minutes:
+eyJ2ZXIiOiI4LjAuMCIsImFkciI6WyIxOTIuMTY4Ljg2LjEyMjo5MjAwIl0sImZnciI6ImU5MmVhYWM0ZWMzMGExY2EzMDA0MzM4NDgyM2I3Y2YwNTFkMWQ3OTdkNGJlNTQxYzE3ZWY4NGFiMzBjMjlmNGUiLCJrZXkiOiJFM05YNFh3QkVYOVV2SUs0QlU2YTphVEhESktYRVFEbTctUjlFYlBneGlnIn0=
+
+The hex-encoded SHA-256 fingerprint of the generated HTTPS CA DER-encoded certificate:
+e92eaac4ec30a1ca30043384823b7cf051d1d797d4be541c17ef84ab30c29f4e
+
+You can complete the following actions at any time:
+Reset the password of the elastic built-in superuser with
+'bin/elasticsearch-reset-password -u elastic'.
+
+Generate an enrollment token for Kibana instances with
+'bin/elasticsearch-create-enrollment-token -s kibana'.
+
+Generate an enrollment token for Elasticsearch nodes with
+'bin/elasticsearch-create-enrollment-token -s node'.
+----
 
 If you have password-protected the {es} keystore, you will be prompted
 to enter the keystore's password. See <<secure-settings>> for more
@@ -13,14 +48,18 @@ details.
 
 By default {es} prints its logs to the console (`stdout`) and to the `<cluster
 name>.log` file within the <<path-settings,logs directory>>. {es} logs some
-information while it is starting up, but once it has finished initializing it
+information while it is starting, but after it has finished initializing it
 will continue to run in the foreground and won't log anything further until
 something happens that is worth recording. While {es} is running you can
-interact with it through its HTTP interface which is on port 9200 by default.
+interact with it through its HTTP interface which is on port `9200` by default.
+
 To stop {es}, press `Ctrl-C`.
 
-NOTE: All scripts packaged with Elasticsearch require a version of Bash
+NOTE: All scripts packaged with {es} require a version of Bash
 that supports arrays and assume that Bash is available at `/bin/bash`.
 As such, Bash should be available at this path either directly or via a
 symbolic link.
 
+To enroll additional nodes in your cluster, create an enrollment token with the
+`elasticsearch-create-enrollment-token` tool. You can then start a node with the `--enrollment-token` parameter so that it
+{ref}/configuring-stack-security.html#stack-enroll-nodes[joins an existing cluster].

+ 21 - 14
docs/reference/setup/install/targz.asciidoc

@@ -1,16 +1,16 @@
 [[targz]]
-=== Install Elasticsearch from archive on Linux or MacOS
+=== Install {es} from archive on Linux or MacOS
 
-Elasticsearch is as a `.tar.gz` archive for Linux and MacOS.
+{es} is available as a `.tar.gz` archive for Linux and MacOS.
 
 include::license.asciidoc[]
 
-The latest stable version of Elasticsearch can be found on the
-link:/downloads/elasticsearch[Download Elasticsearch] page.
+The latest stable version of {es} can be found on the
+link:/downloads/elasticsearch[Download {es}] page.
 Other versions can be found on the
 link:/downloads/past-releases[Past Releases page].
 
-NOTE: Elasticsearch includes a bundled version of https://openjdk.java.net[OpenJDK]
+NOTE: {es} includes a bundled version of https://openjdk.java.net[OpenJDK]
 from the JDK maintainers (GPLv2+CE). To use your own version of Java,
 see the <<jvm-version, JVM version requirements>>
 
@@ -19,13 +19,13 @@ see the <<jvm-version, JVM version requirements>>
 
 ifeval::["{release-state}"=="unreleased"]
 
-Version {version} of Elasticsearch has not yet been released.
+Version {version} of {es} has not yet been released.
 
 endif::[]
 
 ifeval::["{release-state}"!="unreleased"]
 
-The Linux archive for Elasticsearch v{version} can be downloaded and installed as follows:
+The Linux archive for {es} v{version} can be downloaded and installed as follows:
 
 ["source","sh",subs="attributes"]
 --------------------------------------------
@@ -46,13 +46,13 @@ endif::[]
 
 ifeval::["{release-state}"=="unreleased"]
 
-Version {version} of Elasticsearch has not yet been released.
+Version {version} of {es} has not yet been released.
 
 endif::[]
 
 ifeval::["{release-state}"!="unreleased"]
 
-The MacOS archive for Elasticsearch v{version} can be downloaded and installed as follows:
+The MacOS archive for {es} v{version} can be downloaded and installed as follows:
 
 ["source","sh",subs="attributes"]
 --------------------------------------------
@@ -80,6 +80,8 @@ endif::include-xpack[]
 [[targz-running]]
 include::targz-start.asciidoc[]
 
+:os-dir:       $ES_HOME
+
 include::check-running.asciidoc[]
 
 Log printing to `stdout` can be disabled using the `-q` or `--quiet`
@@ -89,9 +91,9 @@ option on the command line.
 include::targz-daemon.asciidoc[]
 
 [[targz-configuring]]
-==== Configuring Elasticsearch on the command line
+==== Configure {es} on the command line
 
-Elasticsearch loads its configuration from the `$ES_HOME/config/elasticsearch.yml`
+{es} loads its configuration from the `$ES_HOME/config/elasticsearch.yml`
 file by default. The format of this config file is explained in
 <<settings>>.
 
@@ -115,7 +117,7 @@ directories are, by default, contained within `$ES_HOME` -- the directory
 created when unpacking the archive.
 
 This is very convenient because you don't have to create any directories to
-start using Elasticsearch, and uninstalling Elasticsearch is as easy as
+start using {es}, and uninstalling {es} is as easy as
 removing the `$ES_HOME` directory. However, it is advisable to change the
 default locations of the config directory, the data directory, and the logs
 directory so that you do not delete important data later on.
@@ -125,7 +127,7 @@ directory so that you do not delete important data later on.
 |=======================================================================
 | Type | Description | Default Location | Setting
 | home
-  | Elasticsearch home directory or `$ES_HOME`
+  | {es} home directory or `$ES_HOME`
  d| Directory created by unpacking the archive
   |
 
@@ -140,6 +142,11 @@ directory so that you do not delete important data later on.
   | $ES_HOME/config
   | <<config-files-location,ES_PATH_CONF>>
 
+| conf
+  | Generated TLS keys and certificates for the transport and HTTP layer.
+  | $ES_HOME/config/tls_auto_config_<timestamp>
+ d|
+
 | data
   | The location of the data files of each index / shard allocated
     on the node.
@@ -163,5 +170,5 @@ directory so that you do not delete important data later on.
 
 |=======================================================================
 
-
+include::security-files-reference.asciidoc[]
 include::next-steps.asciidoc[]

+ 2 - 0
docs/reference/setup/install/windows.asciidoc

@@ -368,6 +368,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.
 
+:os-dir:       %ES_HOME%
+
 include::check-running.asciidoc[]
 
 [[msi-installer-windows-service]]

+ 2 - 0
docs/reference/setup/install/zip-windows.asciidoc

@@ -85,6 +85,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.
 
+:os-dir:       %ES_HOME%
+
 include::check-running.asciidoc[]
 
 [[windows-service]]